Markdown and MDX – NimbleDocs

The project uses Markdown and MDX for content management.

Markdown

Markdown is a lightweight markup language that you can use to add formatting elements to plaintext text documents.

It is a popular format for writing documentation and is used by many open-source projects (including Next.js).

Frontmatter

Each markdown file includes a frontmatter section at the top of the file that defines metadata for the document. This metadata includes fields like title, description, and publishedAt.

The rest of the file contains the content of the document written in markdown format.

What is MDX?

MDX is an authorable format that lets you seamlessly write JSX in your Markdown documents. You can import components, such as interactive charts or alerts, and embed them within your content. This makes writing long-form content with components a blast.

You write markdown with embedded components through JSX:


1import {Chart} from './snowfall.js'
2export const year = 2018
3
4# Last year’s snowfall
5
6In {year}, the snowfall was above average.
7It was followed by a warm spring which caused
8flood conditions in many of the nearby rivers.
9
10<Chart year={year} color="#fcb32c" />

Which compiles to:

Custom Components

We have a set of custom components that can be used within our MDX files.

We provide few components out of the box, but you can also create your own components.

Callout

The Callout component is used to highlight important information.


1import {Callout} from '@components'
2
3<Callout type="info">
4  This is an important message.
5</Callout>

Quick Link

The QuickLink component is used to link to a page within the site.


1import {QuickLink} from '@components'
2
3<QuickLink href="/about">
4  Learn more about us
5</QuickLink>
6
7<QuickLink href="/contact">
8  Contact us
9</QuickLink>

MDX Plugins

We use a number of MDX plugins to add additional functionality to our MDX files.

remark-gfm

This is a plugin for the Remark processor, which parses and compiles markdown. The remarkGfm plugin adds support for GitHub Flavored Markdown (GFM) to Remark. GFM is a variant of Markdown that is commonly used for writing README files, issues, and pull requests on GitHub. It includes features like tables, strikethrough, task lists, and URL autolinking.

remark-flexible-code-titles

This Remark plugin allows you to add titles to your code blocks in Markdown. It's useful for providing context or additional information about the code snippet that follows.

rehype-slug

This is a plugin for the Rehype processor, which is used to manipulate HTML. The rehypeSlug plugin adds ID attributes to heading elements (h1-h6) in your HTML. These IDs are generated from the text content of the heading, and they are URL-friendly. This is useful for creating anchor links to specific sections of your content.

rehype-autolink-headings

This Rehype plugin automatically adds links to your headings. This is useful for creating a table of contents or for making it easy for users to share links to specific sections of your content. The links are added before or after the text content of the heading, and they use the IDs generated by rehypeSlug.