If you’re looking at info from elsewhere on the web, you’ll quickly discover that Markdown has a simple core syntax and many more complex variations built off of that. On Talarius, we do the same, using CommonMark for our core syntax and adding extensions here and there to fit our needs.
This particular guide covers the core syntax and the variations that are available from the controls of our Markdown editor. To go beyond those controls, check out the Advanced Markdown Guide.
¶ Text Formatting
¶ Paragraphs and Line Breaks
Leave at least one line between paragraphs. That way, there will be a small gap between them on the final page. The gap helps make your text more readable.
Example:
A single sentence all on its own.
A second sentence, also on its own.
Becomes:
A single sentence all on its own.
A second sentence, also on its own.
On the other hand, if you have multiple items that you want to clump together, put them next to each other and they’ll be smushed into one block:
A single sentence all on its own.
A second sentence, uncomfortably close.
A third sentence, completing the sandwich.
Becomes
A single sentence all on its own.
A second sentence, uncomfortably close.
A third sentence, completing the sandwich.
¶ Emphasis
Bold, italics, and strikethrough are easy to do by using the buttons in the editor, or by adding certain characters around the word(s) you want to emphasize:
**Bold**, *italics*, and ~~strikethrough~~ are easy...
Becomes
Bold, italics, and strikethrough are easy…
Strikethrough is an extension.
Underline is also supported on Talarius, by wrapping your text in a single underscore:
_underlined_ text
Becomes
underlined text
Be sparing with your underlines and try to use other ways to convey emphasis whenever possible.
Underline formatting is explicitly not supported in almost all other markdown parsers, because it looks confusingly similar to a browser’s standard link formatting. Underlined text from Talarius will appear in italics everywhere else that markdown is used.
¶ Subscript and Superscript
In case you need to use them, subscript and superscript are equally easy to do with the buttons or with special characters:
Word~Subscript~
Word^Superscript^
WordSubscript
WordSuperscript
There are some limitations to how subscript and superscript can be used:
- Only a single contiguous word can be affected. So H2O works fine, but H~two times~O does not.
- You can’t add any other styling to a sub- or superscript word. So kprime works, but k**prime** does not.
For better control and more complex formulas, take a look at the LaTeX Formulas in the advanced guide.
Both superscript and subscript are extensions
¶ Links
Links are fully supported by Markdown, using the format [link text](link/url/path). However, it’s much easier to just use the link tool on the left of the editor.
[home page](/home)
becomes
¶ Images
Embedding images is just as easy as links. Images use the format , but it’s way way easier to use the Insert Asset tool on the left.
Becomes
It’s a good idea to change the text inside square brackets to say something besides the name of the image. That text will be displayed any time the image can’t load, for any reason.
You can do a bunch of advanced things with images, like change their dimensions, or add hover text. See the advanced guide for details.
¶ Image Position
When you insert an image, you can position it to the left of text, to the right of text, or centered on the page. If you want to change the position later, it’s easy to do by adding some text to the end of the image line. This makes use of a pattern that you’ll see a lot in the advanced guide where a special class is added on to an existing element by using curly braces.
{.align-right}
Becomes
Play with the styles and see what works for you!
Available style classes:
.align-right- image floats to the right of text.align-left- image floats to the left of text.align-center- image sits in the center of the page- none - image on its own
¶ Blockquotes
The blockquote button lets you put quotes in a special box.
> The simple blockquote is great, especially for longer quotations. You can put other formatting *within* a blockquote, too!
Becomes
The simple blockquote is great, especially for longer quotations. You can put other formatting within a blockquote, too!
¶ Special Blockquotes
There are also some variants of blockquotes for highlighting special information. These make use of the same pattern as image position, using curly braces to add a special class to a blockquote.
Use these special quote blocks sparingly!
¶ Info Boxes
These are for calling out special, but neutral information, like a tiny sidebar or helpful tip.
> Attaching classes using `{.class-name}` is an extension
{.is-info}
Becomes
Attaching classes using
{.class-name}is an extension
¶ Success Boxes
These are for highlighting positive information.
> These unnamed new gear items are available to everyone!
{.is-success}
Becomes
These unnamed new gear items are available to everyone!
¶ Warning Boxes
These are for calling out potentially disruptive information, like stuff you would expect to throw someone off.
> Some changes are especially impactful for Barbarians. Check your feats to make sure you still qualify!
{.is-warning}
Becomes
Some changes are especially impactful for Barbarians. Check your feats to make sure you still qualify!
¶ Danger/Error Boxes
These are for calling out dangerous or truly disruptive information.
> Never, and I mean **never**, cast a fireball while standing in an oil refinery!
{.is-danger}
Becomes
Never, and I mean never, cast a fireball while standing in an oil refinery!
¶ Example Box
This is an extension of the existing blockquote classes. There’s a button for it near the top of the Blockquotes menu.
> For example, say Alice wants to make a boat. She asks Bob to source
> the materials, but first they need to decide on what kind of boat.
> Is it a wooden rowboat? A canoe? A small fiberglass sailing boat? A
> pleasure yaght fit for ocean travel? It's important to figure these
> things out beforehand.
{.is-example}
Becomes
For example, say Alice wants to make a boat. She asks Bob to source the materials, but first they need to decide on what kind of boat. Is it a wooden rowboat? A canoe? A small fiberglass sailing boat? A pleasure yaght fit for ocean travel? It’s important to figure these things out beforehand.
¶ Game Summary Card
This is another extension of the existing blockquote classes. There’s a button for it at the bottom of the Blockquotes menu.
> ## [Game Title](/games/game-name)
> **System:** System Name
> **GM:** GM's name
> **Summary:** A brief summary or pitch for the game. Keep it to a few short sentences.
{.is-game}
Becomes
¶ Game Title
System: System Name
GM: GM’s name
Summary: A brief summary or pitch for the game. Keep it to a few short sentences.
This block is supposd to be used only for game summary cards, and only on the wiki’s front page. If you want to use it somewhere else, please just use it for game summaries!
¶ Asides
Asides are useful for brief pieces of text that tangentially relate to the page’s main contents. They float to the side, out of the way, and should be kept to a few sentences at most. Anything longer should be part of the main content or even get its own page.
This extension of the blockquote class lets you create sidebars with a little text inside. These asides are great for sprinkling in some commentary or choice quotes related to the topic at hand.
The aside in this section was made with this code:
> Asides are useful for brief pieces of text that tangentially relate to the page's main contents. They float to the side, out of the way, and should be kept to a few sentences at most. Anything longer should be part of the main content or even get its own page.
{.is-aside}
You should still use info, warning, and danger boxes to highlight important information. Asides are for tangential, interesting info that is not strictly needed for the content.
¶ Lists
¶ Bulleted Lists
Bulleted lists are made by having an asterisk or a dash in front of each item. For sanity, try to use the same starting character for each level of a list.
* First item
* Second item
- Nested item
+ Deeper nesting!
- Another nested item
* Third item
Becomes
- First item
- Second item
- Nested item
- Deeper nesting!
- Another nested item
- Nested item
- Third item
¶ Link Lists
Lists of links can be made by adding the .links-list class to a bulleted list, or with the Links List button:
* [link 1]()
* [link 2]()
* [link 3]()
{.links-list}
Becomes
¶ Link Descriptions
Within the links of a link list, italic text can be used to add a description of the link. Like the link itself, this text can be clicked to visit the page:
* [link 1*Description of link 1*]()
* [link 2*Description of link 2*]()
* [link 3*Description of link 3*]()
{.links-list}
Becomes
¶ Explanatory Text
Text after a link gets put immediately below it, which is useful for brief explanatory text about the link. Unlike the link and its description, clicking on the explanatory text will not visit the linked page.
* [link 1]() Additional information that needs additional space
* [link 2*Description of link 2*]() Extra information that needs extra space
{.links-list}
Becomes
- link 1 Additional information that needs additional space
- link 2Description of link 2 Extra information that needs extra space
¶ Grid Lists
Grid lists do away with the bullet in front of each item and instead shade every other item, or with the Grid List button:
* Defense: 2
* Speed: 5
* Size: 5
* Some other stat: lots
* Small thing
* Looooooooooooooooong thing
{.grid-list}
Becomes
- Defense: 2
- Speed: 5
- Size: 5
- Some other stat: lots
- Small thing
- Looooooooooooooooong thing
This can be useful for certain stat blocks.
¶ Numbered Lists
For a numbered list, put a number and period before each item. The numbers don’t have to be right; the browser will format the numbers correctly. Still, it’s more readable if they’re in order.
1. First item
2. Second item
1. nested number
1. doubly-nested number
3. Third item
* nested bullet
Becomes
- First item
- Second item
- nested number
- doubly-nested number
- nested number
- Third item
- nested bullet
You can mix and match nested types of list to youre heart’s content.
¶ To-do Lists
If you want a list with checkboxes, you can use the to-do list:
* [ ] Not checked
* [ ] Not checked
* [x] Yes checked
Becomes
- Not checked
- Not checked
- Yes checked
While you can’t click them, they do look pretty. This works both for bullet lists and numbered lists.
Though they resemble bulleted lists, you cannot apply bulleted list styles like grid lists or link lists to a to-do list.
¶ Inline Code
You can make a few words look monospaced like code by surrounding them with backticks, or using the code button.
The technomancer wasn't really a wizard, he just knew what the `C:\` drive was.
Becomes
The technomancer wasn’t really a wizard, he just knew what the C:\ drive was.
¶ Keyboard Keys
If you need to format something to resemble a keyboard key, surround it in <kbd> html tags, or use the Keyboard Key button.
Telling someone to press <kbd>Ctrl</kbd> + <kbd>Alt</kbd> + <kbd>Delete</kbd> won't work on a Mac.
Becomes
Telling someone to press Ctrl + Alt + Delete won’t work on a Mac.
This introduces another advanced topic: embedded HTML. We try to avoid using embedded HTML on the wiki, so it’s mostly kept in the advanced guide. The
<kbd>tag is the only exception.
¶ Page Organization
Our wiki automatically generates a table of contents for every page. To do so, it uses the headers within the page. Headers are not the only way to divide a page, though.
¶ Headers
Page headers come in a hierarchy and are made by putting one or more hash marks (#) at the start of a line, or by using the H# header button.
For example, the headers for this section look as follows in the source:
# Page Organization
...
## Headers
...
Only the first two levels of header are included in the page’s table of contents, so plan accordingly.
¶ Dividers
If you need to visually separate content on a page without adding a header, the dividing line (or horizontal bar) is a good option.
Some text
---
Completely different content
Becomes
Some text
Completely different content
If you find yourself using dividers a lot, it might mean that your page has lots of disparate sections that could be better served by being on their own page.
¶ Page Length
We have no limits on page length. However, if you find your page is getting too long to manage, consider splitting some content into a sub-page and linking to it.