Custom tags

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.

AttributeDefaultDescription
byName 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.

AttributeDefaultDescription
captionThe caption to go under the example
tutorialfalseSet this to show the Code tab first, rather than the default Preview tab. Also, additional options are made available for use in pattern examples
previewFirstfalseSet this to always show the Preview tab first, regardless of the value of tutorial
withHeadfalseSet this to include a head measurement (for tutorial pattern examples)
paperlessfalseSet this to enable paperless mode
settingsA YAML string of settings to take into account
Path.curve()

Fixme

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

AttributeDefaultDescription
compactfalseRenders 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.

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

ReadMore

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.

AttributeDefaultDescription
recursefalseInclude all child-pages and sub-child-pages in the entire directory tree
markdown
<ReadMore />

(It won’t show anything on this page, since this page has no child-pages.)

Use Related to add something that is relevant to the current topic.

AttributeDefaultDescription
compactfalseRenders compact variant
Related

This snippet is provided by the buttons plugin

Related|

Tip

Use Tip for, you know, tips.

AttributeDefaultDescription
compactfalseRenders compact variant
Tip

The notches on the shoulder and sleeve parts are used to help with alignment when attaching the sleeve.

Tip|

Align the notches so they match

Warning

Use Warning when you want to warn the reader of potential danger or unintended side-effects.

AttributeDefaultDescription
compactfalseRenders compact variant
Warning
Please make a backup

Following these instructions will remove all your data

Warning|

Take it slow

YouTube

The YouTube tag will embed YouTube videos or YouTube playlists responsively.

AttributeDefaultDescription
idID of the YouTube video or playlist
playlistfalseSet this when embedding a playlist