Learn Markdown

Source

mdsvex reads its own flavour of markdown, Penguin-Flavoured Markdown. It is CommonMark with the ambiguous parts taken out, the GFM additions most people use, and a few of its own. Most of a document reads as it does anywhere else. This section covers the rest.

Coming from 0.x, the migrator rewrites your documents for you.

CommonMark reads _text_ and *text* both as emphasis. mdsvex reads _text_ as emphasis and *text* as strong.

You write
_text_ and *text*

CommonMark

text and text

<p><em>text</em> and <em>text</em></p>

mdsvex

text and text

<p><em>text</em> and <strong>text</strong></p>

CommonMark reads them as strong. mdsvex reads strong inside strong, and emphasis inside emphasis.

You write
**text** and __text__

CommonMark

text and text

<p><strong>text</strong> and <strong>text</strong></p>

mdsvex

text and text

<p><strong><strong>text</strong></strong> and <em><em>text</em></em></p>

Write *text*.

CommonMark reads a heading. mdsvex reads a paragraph, and --- is a thematic break.

You write
Title
===

Title
---

CommonMark

Title

Title

<h1>Title</h1>
<h2>Title</h2>

mdsvex

Title ===

Title


<p>Title ===</p>
<p>Title</p>
<hr />

Write # Title.

CommonMark drops the closing #. In mdsvex they are text.

You write
## Title ##

CommonMark

Title

<h2>Title</h2>

mdsvex

Title ##

<h2>Title ##</h2>

CommonMark reads a code block. In mdsvex it is nothing, indentation means nothing.

You write
    code

CommonMark

code
<pre><code>code
</code></pre>

mdsvex

code

<p>code</p>

Use a fence.

CommonMark reads a code fence. In mdsvex it is text.

You write
~~~
code
~~~

CommonMark

code
<pre><code>code
</code></pre>

mdsvex

~~~ code ~~~

<p>~~~ code ~~~</p>

A fence is three or more backticks.

CommonMark reads a line break. In mdsvex they are nothing.

You write
one  
two

CommonMark

one
two

<p>one<br /> two</p>

mdsvex

one two

<p>one two</p>

End the line with a backslash.

In CommonMark it is still in the quote. In mdsvex the quote has ended.

You write
> quoted
not quoted

CommonMark

quoted not quoted

<blockquote>
	<p>quoted not quoted</p>
</blockquote>

mdsvex

quoted

not quoted

<blockquote>
	<p>quoted</p>
</blockquote>
<p>not quoted</p>

CommonMark reads a link. In mdsvex it is text.

You write
[svelte]: https://svelte.dev/

Made with [svelte].

CommonMark

Made with svelte.

<p>Made with <a href="https://svelte.dev/">svelte</a>.</p>

mdsvex

Made with [svelte].

<p>Made with [svelte].</p>

Write [text][], with the definition above it.

CommonMark reads text. mdsvex reads a Svelte expression.

You write
One and one is {1 + 1}.

CommonMark

One and one is {1 + 1}.

<p>One and one is {1 + 1}.</p>

mdsvex

One and one is 2.

<p>One and one is 2.</p>

Write \{ for a brace.

A link reference definition comes before the first link that uses it. That lets a document render while it is still arriving, since nothing later in it can change what came before.

You write
[svelte]: https://svelte.dev

Made with [svelte][], see [the site][svelte].
You get
Compiles to
<p>
  Made with <a href="https://svelte.dev"
    >svelte</a
  >, see
  <a href="https://svelte.dev"
    >the site</a
  >.
</p>

A _ or * opens after a space or punctuation and closes before one, so snake_case_name and 2*3*4 are text. To mark part of a word, put a | on the side that touches a letter. The | is not rendered:

You write
fan|_tas_|tic
You get
Compiles to
<p>fan<em>tas</em>tic</p>

Curly quotes, dashes and other Unicode punctuation count as punctuation there. Chinese, Japanese and Korean text needs no marker, 这是*重要*的 is strong.

H~2~O

subscript, H2O

x^2^

superscript, x2

~~gone~~

strikethrough

- [x] done
a pipe table

a table, with header columns and merged cells

:name[text], ::name, :::name

a directive, your own component

a math fence, $`x^2`$
[^1] in the text and [^1]: a note
import lines at the top

imports without a <script>

A list item that starts with [ ] or [x] and a space is a task:

You write
- [x] write the docs
- [ ] ship it
You get
Compiles to
<ul>
  <li>
    <input
      type="checkbox"
      checked
      disabled
    /> write the docs
  </li>
  <li>
    <input type="checkbox" disabled /> ship
    it
  </li>
</ul>

It works in bulleted and numbered lists at any depth.

A replaced li gets checked and no checkbox.

  • The marker needs text after it on its line, so [x]done and a bare - [ ] are text, and so is a marker anywhere but the start of an item.
  • Write - \[x] text to start an item with those characters.

Tables are GFM pipe tables. A : in the delimiter row aligns a column, and \| is a bar inside a cell, in a code span too.

A || in the header and delimiter rows makes the columns on one side of it row headers:

You write
| option || type | default |
| --- || --- | --- |
| `extensions` || `string[]` | `['.svx']` |
You get
Compiles to
<table>
  <thead>
    <tr>
      <th>option</th>
      <th>type</th>
      <th>default</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row"
        ><code>extensions</code></th
      >
      <td><code>string[]</code></td>
      <td><code>['.svx']</code></td>
    </tr>
  </tbody>
</table>

A cell that holds only > joins the cell to its left, and one that holds only ^ joins the cell above:

You write
| a | > | c |
| --- | --- | --- |
| 1 | 2 | 3 |
| ^ | 4 | 5 |
You get
Compiles to
<table>
  <thead>
    <tr>
      <th colspan="2">a</th>
      <th>c</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td rowspan="2">1</td>
      <td>2</td>
      <td>3</td>
    </tr>
    <tr>
      <td>4</td>
      <td>5</td>
    </tr>
  </tbody>
</table>
  • Write \> or \^ for a cell of that one character.
  • A row is one line, and a table ends at a blank line or at any line that would end a paragraph, such as a heading.

Components, elements, expressions and blocks go anywhere, and markdown works inside them with no blank lines around it:

You write
<Box>
# A title
</Box>

{#if published}
Some *strong* text.
{/if}
You get
Compiles to
<Box><h1>A title</h1></Box
>{#if published}
  <p>
    Some <strong>strong</strong> text.
  </p>{/if}

A block quote, a list item, an element, a Svelte block and a container directive all hold the same blocks the document does, so a table or a {#if} is the same thing inside a list item as at the top.

<Chart /> on a line of its own is the component and nothing else, and <Badge /> new today is a paragraph.

You write
<Chart />

<Badge /> new today
You get
Compiles to
<Chart />
<p><Badge /> new today</p>

They stand after any frontmatter, without a <script>, and go into the document's script:

You write
import Chart from './Chart.svelte'

<Chart />
You get
Compiles to
<script>
  import Chart from './Chart.svelte';
</script>

<Chart />

For a brace as text, write \{, use &#123;, or put it in code, where a brace is always text.

You write
One and one is {1 + 1}, not \{1 + 1}.
You get
Compiles to
<p>
  One and one is {1 + 1}, not &#123;1 +
  1}.
</p>

Back to page index

mdsvex, markdown with Svelte in it. MIT licence.