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.

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

Markdown headings create nested <section> elements automatically:

## Introduction

Some text.

### Background

More text.

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

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

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

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();
};
```

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>

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