Skip to content

markdown

Jump to bottom Edit New page
Marcos Caceres edited this page Mar 27, 2026 · 24 revisions

Using Markdown with ReSpec

ReSpec supports GitHub Flavored Markdown (GFM) for writing specification content.

Enable globally

var respecConfig = {
  format: "markdown",
};

With format: "markdown", the entire <body> is treated as Markdown. Keep all content flushed to the left — whitespace is significant in Markdown.

Enable for a single section

<section data-include="my-section.md"
         data-include-format="markdown"></section>

Automatic sectioning

Markdown headings create nested <section> elements automatically:

## Introduction

Some text.

### Background

More text.

Custom heading IDs

## My Heading {#my-custom-id}

Figures

An image with a title becomes a <figure> with <figcaption>:

![alt text](diagram.svg "Caption for the figure")

Code blocks

Use triple-backtick fences with a language hint:

```js
async function fetchData() {
  return await fetch("/api/data.json");
}
```

For WebIDL blocks:

```webidl
[Exposed=Window]
interface Example {
  undefined doThing();
};
```

Mixing HTML and Markdown

HTML elements and Markdown can be mixed, but require a blank line between the tag and the content:

<div class="note">

This is **Markdown** inside an HTML element.

</div>

Notes

  • Markdown is interpreted as GFM — standard Markdown plus tables, strikethrough, and task lists
  • All ReSpec HTML features (xref, dfn panels, WebIDL, lint rules) work inside Markdown content
  • To prevent auto-linking of URLs in code blocks, add class="nolinks" to the <pre> element
  • Whitespace matters — keep Markdown content aligned to the left margin

💖 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

Linting rules

Internal properties

Handled by ReSpec for you.

Special <section> IDs

HTML elements

Custom Elements

HTML attributes

CSS Classes

Special properties

Clone this wiki locally