Markdown Guide

reasonml.org defines a set of markdown components to be able to provide a nice looking document when rendered to a webpage. This document gives an overview over all available components and demonstrates some use-cases.

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
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>

Warning: This might look dangerous

UrlBox

<UrlBox href="/docs/manual/latest/introduction" text="Language Manual"> This is how you define a UrlBox </Url>

Examples:

Check out the officially deployed version of this website (via absolute URL)

We also support markdown inside this component. Relative links will be handled by NextJS Links.

Try multiple paragraphs for instance!

Cite

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

No Designer Ever
<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.

Hinter eines Baumes Rinde wohnt die Made mit dem Kinde, sie ist Witwe, denn der Gatte, den sie hatte, viel vom Blatte. Diente so auf dieser Weise einer Ameise als Speise.

<Intro> Your hero text </Intro>

Codeblocks

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

RE
let a = "This is a Reason codeblock";
The default language is set to `text` and will not provide any syntax highlighting