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:
RElet 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>
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."
<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
RElet a = "This is a Reason codeblock";
The default language is set to `text` and will not provide any syntax highlighting