Table of Contents

• Directory structure
• Headings
• h1 heading
  • h2 heading
    • h3 heading
• Inline styles
• Lists
• Links
• Tables
• Typographic replacements
• Checklists
• Footnotes
• Blockquotes
• Code and Syntax Highlighting
• Images
  • Relative Images

The remark-toc extension auto-generates a table of contents based on a case insensitive Regex match of the heading.
You can either use contents, table of contents or just toc.

Directory structure

All posts live in the posts/ directory in the root of the project, this directory is explicitly allowed to be read by vite.
Articles created in markdown files can live under the root posts/ directory, or be nested inside a folder (for better organization for assets like images).

You can also add multiple articles to a “collection” (or group), all you need to do is nest them inside a folder with a specific syntax. The folder name should be wrapped in square brackets, then the parser will add a special label to the post, which will be displayed both on the post listing and on the article itself.

Example directory structure:

posts/
├── [a_collection]/
│   ├── post1.md
│   ├── post2.md
│   └── post3.md
├── silly/
│   ├── cats.md
│   └── kitty.png
└── how_to_bake_bread.md

Headings

Each heading has a permalink

h1 heading

h2 heading

h3 heading

h4 heading

h5 heading

h6 heading

Inline styles

The ^superscript and _subscript functionality is provided by the remark-sub-super extension, and the deleted and inserted functionality by remark-ins

This text is bold, italic, deleted and inserted
You can also use underscores for bold or italic text.

Here is a code element, ^sup and _sub

Lists

Unordered

• Create a list by starting a line with +, -, or *
  • Sub-lists are made by indenting 4 spaces:
    • Very easy!

Ordered

1. Look at me I’m ordered!

   • You can also mix and match

2. Buy bread

3. You can use sequential numbers…

4. …or keep all the numbers as 1.

Or even start numbering with offset

57. foo
58. bar

Links

I’m an inline-style link
I’m an inline-style link with title

I’m a reference-style link
You can use numbers for reference-style link definitions

Or leave it empty and use the link text itself.

• Just paste links directly in the document like this: https://example.com.
  • URLs in angle brackets work too https://example.com
• An email address: fake.email@email.com.

Tables

Colons can be used to align columns.

Typographic replacements

Checklists

• Task 1
• Task 2
• Look, i can ^also have styling
• Buy bread

Footnotes

This is enabled by the remark-footnotes@2.0 extension.

Footnote 1 link^first
Footnote 2 link^second
Duplicated footnote reference^second

I am a very handsome boy^{[citation needed]}

Blockquotes

Blockquotes are very handy in email to emulate reply text. This line is part of the same quote.

Quote break.

Blockquotes can also be nested…

…by using additional greater-than signs right next to each other…

…or with spaces between arrows.

It can also have code blocks in them:

if __name__ == "__main__":
  print("Hello, World!")

Code and Syntax Highlighting

The code block functionality is provided by shiki which integrates directly with MDsveX.

Example CSS code

@font-face {
    font-family: Chunkfive; src: url('Chunkfive.otf');
}

body, .usertext {
    color: #F0F0F0; background: #600;
    font-family: Chunkfive, sans;
}

@import url(print.css);
@media print {
    a[href^=http]::after {
        content: attr(href)
    }
}

Meta properties

Thanks to transformers from the @shikijs/transformers package, we can add special features by passing meta properties to code blocks.

```js {1}
let a = "This code block will have highlighted lines";
```

```js /words/
let b = "This code block will have highlighted words";
```

```js
let b = "This code block will have highlighted words";  // [!code --]
let c = "This code block will have highlighted diff changes";  // [!code ++]
```

```js title="JavaScript sample"
let d = "This code block will have a title";
```

Working example:

function $initHighlight(block, cls) {
    try {
        if (cls.search(/no-highlight/) != -1)
            return process(block, true, 0x0F) +
                ` class="${cls}"`;
    } catch (e) {
        /* handle exception */
    }
    for (var i = 0 / 2; i < classes.length; i++) {
        if (checkCondition(classes[i]) === undefined)  
            console.log('undefined'); 
    }
}

export $initHighlight;

Images

Here’s a logo (hover to see the title text):

Inline-style:

Reference-style:

Like links, Images also have a footnote style syntax
With a reference later in the document defining the URL location

Relative Images

Thanks to a custom assets/[slug] route, which grabs all images living in the posts directory and serves them under a single path, we can now prepend all nested images in the same directory as the post with /assets/!

You can use .png, .jpg or .gif files.