Skip to content

markdown

Jump to bottom Edit New page
Daniel McNally edited this page Apr 30, 2024 · 23 revisions

Using Markdown with ReSpec

You can use markdown to write ReSpec based documents. But you must follow markdown's rules carefully.

To enable markdown globally, set format to "markdown" (see below). And, in the <body>, make sure you keep all text flushed to the left. This is required because whitespace is significant in Markdown.

<html>
<title>Using Markdown</title>
<script>
var respecConfig = {
  format: "markdown"
}
</script>
<body>

<section id="abstract">

Showing how to use Markdown.

</section>

<section id="sotd">

Custom paragraph.

</section>

## This is a heading

I'm a paragraph.

 * list item
 * another list item

</body>
</html>

The markdown is interpreted as Github Flavored Markdown (GFM) and you can mix HTML and markdown.

Now, we describe some of the ReSpec specific markdown behaviors and extensions.

Automatic sectioning

When using markdown, you don't need to add <section> elements manually. Each heading automatically creates a structure of nested section elements around it. For example:

## Heading

Here's some text.

### Sub heading

More text.

will be transformed into:

<section>
  <h2>Heading</h2>
  <p>Here's some text.</p>
  <section>
    <h3>Sub heading</h3>
    <p>More text.</p>
  </section>
</section>

Custom Heading IDs

By default, ReSpec uses heading's text content to generate IDs for you. The IDs are mostly stable, i.e., we make sure updates to ReSpec do not change the IDs). Sometimes, you might want to add a different (perhaps shorter) ID. You can provide a custom heading ID as:

## I'm a heading {#custom-heading-id}

Figures

If there's a title part in a markdown image, it's treated as a <figcaption>. So:

![alt text 1](src1.png)
![alt text 2](src2.png "title")

is converted into:

<img src="src1.png" alt="alt text 1" />
<figure>
  <img src="src2.png" alt="alt text 2" />
  <figcaption>title</figcaption>
</figure>

Code blocks

You can use triple-backticks to create code-blocks (<pre>/<code> elements). Respec supports syntax highlighting of various languages.

```js
function hello() {
  console.log("hey!");
}
```

And for WebIDL:

```webidl
[Exposed=Window]
interface Paint { };
```

Links in code blocks

The markdown parser automatically converts any URLs into anchors, including those found in code blocks.

You can turn off that functionality by adding the .nolinks css class. Sadly, it means you have to use a <pre> element to create a code block.

<pre class="js nolinks">
async function() {
   // https://example.com won't link
   neitherWillThis("https://example.com");
}
</pre>

HTML and Markdown

Please remember that markdown requires double newlines between an HTML tag and markdown text.

Whitespace is also significant! So, keep things aligned to the left.

<aside class="note">

## Markdown inside HTML tags

This is the correct way to insert markdown inside HTML.

</aside>

💖 Support ReSpec by becoming a sponsor via Open Collective. 💖

✨ View rendered version of this documentation at https://respec.org/docs/ ✨

Guides

Configuration options

W3C Configuration options

Linter rules

Internal properties

Handled by ReSpec for you.

Special <section> IDs

HTML elements

Custom Elements

WebIDL

HTML attributes

CSS Classes

Special properties

Clone this wiki locally