¶ Markdown in Wiki.js Basics
The Markdown in Wiki.js is pretty standard Markdown, but there are few Wiki.JS specific implementations.
Wiki.js has a quick reference guide for Markdown:
Click on the Circle with Question Mark at the bottom left of the Wiki.js window.
This page expands a lot on that quick reference guide.
It shows examples of most of the markdown options, first showing the rendered markdown, followed by the markdown code used to create it.
Wiki.js supports the full CommonMark specs as well as some extensions such as Github Markdown addons.
¶ Headings
Just like HTML, there are 6 levels of headings.
1 being the biggest and 6 the smallest.
In Wiki.js, heading levels 1 and 2 are used to create the table of contents for that page.
¶ Heading 1
¶ Heading 2
¶ Heading 3
¶ Heading 4
¶ Heading 5
¶ Heading 6
Markdown to create the above headings
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6
¶ Tabs
You can create tabs to organise information and make efficient use of the screen area.
You create a tab using the # just like with creating headers. eg # Header.
While you can include Headers in Tab controls, you can't use the same header level that you use to create the Tab.
In this example, Header 1 is used to create the parent table, and Header 2 is to create each Tab element, so Headers 3 thru 6 are available inside each Tab.
You create a Tab control by adding {.tabset} to a header. This header won't be rendered
You then create individual Tab sections by using header elements 1 level higher.
If you use # to create the Tab parent, use ## for the individual sections.
If you use ## for the parent, use ### for the sections.
Whatever header levels remain can be used inside the tab, so if you use # and ## to create the Tabs, you can user header levesl 3-6 for actual headings inside the Tabs
¶ A header to show you can still use headers in Tabs
Tabs can contain most other markdown.
¶ Table
| Name | Age |
|---|---|
| Craig | 18 |
A code block showing some Go code
func main() {
fmt.Println("Hello World!")
}
Some Javascript Code
// the hello world program
document.write('Hello, World!');
Here is the markdown to create a basic tab shown below
# tab parent control {.tabset}
## tab 1
text shown in tab 1
## tab 2
text shown in tab 2
## tab 3
text shown in tab 3
¶ This is an example tab that shows the result from the markdown code in the above Tab
text shown in tab 1
text shown in tab 2
text shown in tab 3
¶ Text Formatting
¶ Bold
Use a double asterisk to make text bold
Use a **double asterisk** to make text **bold**
¶ Italics
Use a single asterisk to make text italic
Use a *single asterisk* to make text *italic*
¶ Underlined
(Wiki.js specific)
Use an underscore to make text underlined
Use an underscore to make text _underlined_
¶ Superscript and subscript
This text is superscript
This text is ^superscript^
This text is subscript
This text is ~subscript~
¶ Strikethrough
This text has strikethrough
This text has ~~strikethrough~~
¶ Highlighting Text
It is ==very important== that you do what exactly what I say
It is ==very important== that you do what exactly what I say
¶ Keyboard Keys
It can be handy in documents to represent keys that the user should be pressing.
Press CTRL + C to cancel
Press <kbd>CTRL</kbd> + <kbd>C</kbd> to cancel
¶ Horizontal Line
You can add a horizontal line that goes the full width of the page to break up the page visually by adding 3 dashes.
Don't add these 3 dashes on a line immediately following other text, otherwise it interprets as making that text a Heading #2. Add a blank line between the text and 3 dashes
Add a horizontal line below this text
There is a horizontal line above this text
Add a horizontal line below this text
---
There is a horizontal line above this text
¶ Links
You can create links to documents internal and external to the Wiki
The format is the text to be displayed in square brackets followed by the web page you are linking to in round brackets:
[Link text](web_page_you_are_linking_to)
For internal documents, you can just refer to the interal document name. Any headings in a Wiki.js document are tagged with an id, so you can refer to that id and link direct to that part of the document.
If you view the rendered document you want to link to, and hover over the header you want to link to. At the right of the windows a ¶ symbol will appear. Right Click and select Copy Link Address. Paste that into a markdown link.
You can also add a HTML element into the Wiki document with an id attribute and link to that.
A link to the top of this document
A link to the top of this document that opens in a new browser tab
A link to Google that opens up in this browser tab
A link to Google that opens up in a seperate browser tab
[A link to the top of this document](/coding/markdown#markdown-in-wikijs-basics)
[A link to the top of this document that opens in a new browser tab](/coding/markdown#markdown-in-wikijs-basics){target=_blank}
[A link to Google that opens up in this browser tab](https://www.google.com)
[A link to Google that opens up in a seperate browser tab](https://google.com){target=_blank}
¶ Fancy Links
You can fancy up a link of links using the {.links-list} class
Standard list of links
If you add the class {.list-link} you get
Standard links
- [link1 - this is a link to one](/coding/markdown#links)
- [link2 - this is a link to two](/coding/markdown#links)
If you add the class `{.list-link}`
- [link1 *this is a link to one*](/coding/markdown#links)
- [link2 *this is a link to two*](/coding/markdown#links)
{.links-list}
¶ Code
The typical way of represending programming code in markdown shows it with a different background colour and a monospaced font.
For a single line, or part of a line, use a single backtick
For a single line, or part of a line, use a `single backtick`
To highlight a block of quote, use triple backticks.
This also adds the option of using syntax colour highlighting for many programming languages, and adds a copy button at the top right of the box, so the code can be copied into the users clipboard. Below is markdown syntax highlighting
```
This is just a generic block of
code with No syntax no colouring.
```
You can add syntax colour highlighting for many programming languages, including markdown itself
```markdown
For a single line, or part of a line, use a `single backtick`
This is **bold**, *italics* and _underlined_
```
¶ Block Quotes
These are frequently used in documentation to call attention to warnings, notes and tips.
This is an unstyled blockquote
This is a blockquote styled to show information
using{.is-info)
A blockquote showing success
in something using{.is-success}
A blockquote showing
a warning using{.is-warning}
A blockquote showing
DANGER using{.is-danger}
This is another
success blockquoteWith a nested nested
blockquote in side it.
Use Emojis to add meaning to block quotes
Tip: Remember to enjoy your life
🔒 Tip: Lock the pilots office before leaving for the nivght
> This is an unstyled blockquote
> This is a blockquote styled to show information
> using `{.is-info)`
{.is-info}
> A blockquote showing success
> in something using `{.is-success}`
{.is-success}
> A blockquote showing
> a warning using `{.is-warning}`
{.is-warning}
> A blockquote showing
> DANGER using `{.is-danger}`
{.is-danger}
> This is another
> success blockquote
>> With a nested nested
>> blockquote in side it.
{.is-success}
Use Emojis to add meaning to block quotes
> :bulb: **Tip:** Remember to enjoy your life
{.is-info}
> 🔒 **Tip:** Lock the pilots office before leaving for the nivght
{.is-warning}
¶ Task Lists
Tasks lists, also referred to as checklist and todo lists.
- Finish this markdown document
- update the ops manual
- learn how to fly
- [x] Finish this markdown document
- [x] update the ops manual
- [ ] learn how to fly
¶ Images
You can insert images into a Wiji.js document
While images can be stored as assets within Wiki.js, I don't like doing it as it stores them inside a database rather than individual files.
Seeing I have access to S3 buckets on AWS, my preference is to host them there unless they are very small.
Regardless of where the images are located, you link to them the same way
![Image alternate text](url to image "Image Title)
- Alt text is shown if the image can't be loaded for some reason
- "Image Title" is what the user sees if they hover over the picture.
- There is a Wiki.js tool in the left toolbar to help inserting images.
An image hosted externally
![biplanes](https://images.unsplash.com/photo-1517341392804-5f6daad2d02d?q=80&w=2074&auto=format&fit=crop&ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D "Bi-planes at sunset" =400x)
An image hosted internally
![angry__horse.png](/angry__horse.png "Angry Horse" =300x)
¶ Tables
¶ Basic Tables
To add a basic table use 3 or more hyphens to create each column header, and use pipes | to seperate each columm. Optionally add a pipe on each end of the row
| Name | Age |
|---|---|
| Craig | 18 |
To create the above, the following works, but the 2nd version is recommended
Version 1
Name | Age
--- | ---
Craig | 18
Version 2
| Name | Age |
| --- | --- |
| Craig | 18 |
¶ Alignment
You can set the alignment of columns with:
| Name | Age | Car |
|---|---|---|
| Craigus Hammondus | Eighteen | Holden Ute |
| Dave | 55 | Shitbox ford Mustang |
| Name | Age | Car |
| :--- | :---: | ---: |
| Craigus Hammondus | Eighteen | Holden Ute |
| Dave | 55 | Shitbox ford Mustang |
¶ Formatting Text in Tables
- You can do basic formatting in tables such as links,
codeand emphasis - You can't use headings, blockquotes, lists, horizontal rules or images
- You can use HTML to in many things such as line breaks, lists and headings
| Name | Age | Car |
|---|---|---|
| Bold Underline | Italics | link |
|
|
|
this is code |
An escaped pipe | | ¶ Heading 1 |
| Name | Age | Car |
| :--- | :---: | ---: |
| **Bold** _Underline_ | *Italics* | [link](/link/to/nowhere) |
| <ul><li>This</li><li>is an</li><li>Unordered</li><li>List</li></ul> | | <ol><li>This</li><li>is an</li><li>Ordered</li><li>List</li></ol> |
| `this is code` | An escaped pipe \| | <h1>Heading 1</h1> |
¶ MultiMarkdown tables
This isn't enabled by default in Wiki.JS
In the Admin section, enable it in the Rendering section
| | Grouping ||
First Header | Second Header | Third Header |
------------ | :-----------: | -----------: |
Content | *Long Cell* ||
Content | **Cell** | Cell |
|
New section |
And more | With an escaped '\|' | |
| Grouping | ||
|---|---|---|
| First Header | Second Header | Third Header |
| Content | Long Cell | |
| Content | Cell | Cell |
| New section | ||
| And more | With an escaped '|' |
¶ Multi Markdown Table Rules
- There must be at least one | per line
- The “separator” line between headers and table content must contain only |,-, =, :,., +, or spaces
- Cell content must be on one line only
- Columns are separated by |
- The first line of the table, and the alignment/divider line, must start at the beginning of the line
Other notes:
- It is optional whether you have | characters at the beginning and end of lines.
- The “separator” line uses ---- or ==== to indicate the line between a header and cell. The length of the line doesn’t matter, but must have at least one character per cell.
- To set alignment, you can use a colon to designate left or right alignment, or a colon at each end to designate center alignment, as above. If no colon is present, the default alignment of your system is selected (left in most cases). If the separator line ends with +, then cells in that column will be wrapped when exporting to LaTeX if they are long enough.
- To indicate that a cell should span multiple columns, then simply add additional pipes (|) at the end of the cell, as shown in the example. If the cell in question is at the end of the row, then of course that means that pipes are not optional at the end of that row…. The number of pipes equals the number of columns the cell should span.
- You can use normal Markdown markup within the table cells.
- Captions are optional, but if present must be at the beginning of the line immediately preceding or following the table, start with [, and end with ]. If you have a caption before and after the table, only the first match will be used.
- If you have a caption, you can also have a label, allowing you to create anchors pointing to the table. If there is no label, then the caption acts as the label
- Cells can be empty.
```mermaid
sequenceDiagram
Alice ->> Bob: Hello Bob, how are you?
Bob-->>John: How about you John?
Bob--x Alice: I am good thanks!
Bob-x John: I am good thanks!
Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row.
Bob-->Alice: Checking with John...
Alice->John: Yes... John, how are you?
¶ Comments
Sometimes as the writer of a document, you want to leave comments in the markdown code for your purposes, without having that content rendered to the user, such as a TODO list or a note of where you are up to.
To add a comment, place text inside square brackets, followed by a colon, space, and hash
(blank line is required before the comment for it to work)
[This is a comment that wont render]: #
¶ Footnotes
Footnotes are automatically put at the bottom of the page under a horiontal line
Use [^1] at the location of the footnote in the text, and [^1]: this is the footnote for what will be displayed at the bottom of the page
¶ Usage
This sentence[1] needs a few footnotes.[2]
Markdown code
This sentence[^1] needs a few footnotes.[^2]
[^1]: A string of syntactic words.
[^2]: A useful example sentence.
Footnotes