Writing Markdown
This assumes you are comfortable with the Markdown syntax. Refer to the official guide if you need a refresher.
All the official syntax is supported, with some added features that will be discussed here.
Headers
Only H1 to H4 headers are properly styled.
Refrain from using H5 and H6 headers; they often lead to unnecessary nesting and complexity.
Links
Internal links
When linking to another internal page, always use the absolute page route of that page.
For example, with a directory structure like this:
content/
├── index.md
├── welcome.md
└── nested/
├── index.md
└── hello.md
In order to link from nested/hello.md
to index.md
:
[link](/).
And from welcome.md
to nested/hello.md
:
[link](/nested/hello).
External links
Use it as per normal. The default behaviour will open the external link in a new tab.
Code blocks
Create code blocks by placing triple backticks ```
before and after the block. The language, and the file type/name can also be defined.
For instance, the following in your raw Markdown file,
```js[myFile.js]
console.log("Doconuxt is awesome!");
```
will be rendered as:
console.log("Doconuxt is awesome!");
Math
flavoured math is supported natively. Internally, is used as the rendering engine.
Inline mode
For inline mode, use $
as delimiters.
For example,
$e^{i\pi}$ is really just $1$
Will be rendered as: is really just .
Display mode
For display mode, use $$
as delimiters.
For example,
$$
e^{i\pi} = 1
$$
Will be rendered as:
For display mode to be properly centred, make sure the $$
delimiters are on different lines.
HTML
When using Markdown inside HTML elements, it must be preceded and followed by an empty line for the block to be treated as Markdown. Otherwise, the whole block will be treated as custom HTML.
For example, the following will not be parsed as Markdown:
<div>
1. first
2. second
</div>
But this will:
<div>
1. first
2. second
</div>
Vue components
It is possible to include your own custom Vue components directly in the Markdown.
First, put your components in components/global/
directory and you can start using them in your Markdown without having to import them.
Take note of the caveats:
- Use
kebab-case
, and notPascalCase
when referring to the components- eg.
<my-component>
instead of<MyComponent>
- eg.
- Do no use self-closing tags
- eg.
<my-component></my-component>
instead of<my-component />
- eg.
Refer to the official @nuxt/content documentation for more information.