The way we render Markdown on our websites is through the use of MDX. This allows us to extend Markdown with our own tags. These tags are custom React components.

Such custom components allow us to put things in Markdown content that would typically require a lot more complexity.

Below is a list of custom tags that we support in our Markdown-based documentation, both for freesewing.dev as freesewing.org.

Comment

Use a Comment when you want to illustrate something is a personal opinion or tip/advice rather than the sort more neutral voice used throughout our documentation.

Attribute	Default	Description
`by`		Name of the commenter

Comment by joost

MDX is essentially Markdown + (React) components

joost

Example

The Example tag allows you to embed a FreeSewing code example and have it rendered in the browser. Specifically, you should write a draft method which will then be rendered.

Attribute	Default	Description
`caption`		The caption to go under the example
`tutorial`	`false`	Set this to show the Code tab first, rather than the default Preview tab. Also, additional options are made available for use in pattern examples
`previewFirst`	`false`	Set this to always show the Preview tab first, regardless of the value of `tutorial`
`withHead`	`false`	Set this to include a head measurement (for tutorial pattern examples)
`paperless`	`false`	Set this to enable paperless mode
`settings`		A YAML string of settings to take into account

Fixme

Use Fixme to indicate something needs attention/work but you don’t have time or can’t fix it now.

Attribute	Default	Description
`compact`	`false`	Renders compact variant

FIXME

ToDo

Include link to roadmap
Fix style for text outside paragraphs

FIXME|

Show compact example

Mermaid

Not strictly speaking a custom tag, but by using a fenced code block with the mermaid language, you can generate Mermaid diagrams. Like this:

graph LR; A--> B & C & D; B--> A & E; C--> A & E; D--> A & E; E--> B & C & D;

Note

Use Note to add something that stands out to draw attention.

Attribute	Default	Description
`compact`	`false`	Renders compact variant

Note

Also available in black

This style also comes in black, which we can all agree is the superior color

Note|

And in pink

The ReadMore tag allows you to insert a list of child-pages. The list is automatically generated from the pages in the subdirectories of the documentation page’s directory. This tag is typically used on overview pages, such as our Markdown guide page.