Markdown Guide

How does it work?

We use a toolset called mdxjs to parse and interpret .mdx files within the pages/ directory. The default set for our markdown components is defined in the Markdown.default binding. Each layout in our codebase injects the components via the Mdx.Provider component, kinda like this:

RE
let components = Markdown.default;

<Mdx.Provider components>
  {/*...*/}
</Mdx>

So the Mdx.Provider makes sure that our markdown document looks pretty. Make sure to make use of them!

Markdown JSX Basics

You can use JSX notation inside every .md / .mdx file. We also inject some useful components in there to give your document more visual appeal. There's two ways on how you can pass in JSX children within the markdown syntax:

• As a markdown string

• As a plain string

Whenever you insert a newline after the beginning tag and before the closing tag, the content will be interpreted as nested markdown:

<div>

This **thing** will be parsed as markdown, "thing" will therefore be bold

</div>

If you leave them out, the content will be a plain string without further formatting:

<div>
**this will not be bold**
</div>

Keep this in mind when editing content.

Text Components

Info / Blockquote

The <Info/> component is useful for putting notes into a highlighted section. You can use it via JSX syntax...

<Info> This is a info box </Info>

...or via blockquote syntax:

> This is
> a info box

The Info component is also really useful if you want its children to be parsed as markdown. You can even pass in html elements.

<Info>

**Note:** Some text

</Info>

Note: If you want to use markdown content within a component, make sure to add a newline between the content and the opening / closing JSX tag!

Warn

The <Warn/> component is a useful tool to point out version issues and similar information.

<Warn>

**Warning:** This might look dangerous

</Warn>

UrlBox

<UrlBox href="/docs/manual/latest/introduction" text="Language Manual">

This is how you define a UrlBox

</Url>

Examples:

Cite

<Cite author="No Designer Ever">

"Always, always make the logo bigger, no matter what."

</Cite>

Intro / Chapter Hero

This component is useful to ease the user into the topic. Use it for the first paragraph and give a quick overview on what the document is about.

<Intro>

Your hero text

</Intro>

Codeblocks

Codeblocks are represented via ``` codefences. Following languages are available: res, re, js, ml, text, json, sh

RES
let a = "This is a Reason codeblock"

The default language is set to `text` and will not provide any syntax
highlighting

Highlighting lines

To highlight codelines in your code snippet, use the {range} meta parameter:

```res {1,4-5}

let a = 1
let b = 2

switch a => {
| 1 => a + b
| 2 => a - b
| _ => b
}
```

which will render:

RES
let a = 1
let b = 2

switch a => {
| 1 => a + b
| 2 => a - b
| _ => b
}

CodeTabs

For cases where you want to show a single codeblock with multiple syntaxes, use the <CodeToggle> component. Make sure to leave a newline between the <CodeToggle> JSX tags, otherwise codeblock children won't be recognized!

Example:

<CodeTab labels={["ReScript", "JS Output"]}>

```res
let a = "Some ReScript code"
```

```js {3}
var a = "Some JavaScript code";

var highlighted = "yep"
```

</CodeTab>

Renders to following output:

let a = "Some ReScript code"
switch myValue {

}