Skip to content

markdown

Jump to bottom Edit New page
Marcos Cáceres edited this page May 13, 2021 · 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.

<scrip>
var respecConfig = {
  format: "markdown"
}
</script>
<body>

## This is a heading

I'm a paragraph.

 * list item
 * another list item

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.

Headings

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}

Code blocks

You can use triple-backticks to create code-blocks (<pre> elements). Syntax highlighting for various languages, including an advanced syntax highlighter for WebIDL is available out of the box.

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

And for WebIDL:

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

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