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 |
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 |
ToDo
- Include link to roadmap
- Fix style for text outside paragraphs
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:
Note
Use Note to add something that stands out to draw attention.
Attribute | Default | Description |
---|---|---|
compact | false | Renders compact variant |
Also available in black
This style also comes in black, which we can all agree is the superior color
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.
Attribute | Default | Description |
---|---|---|
recurse | false | Include all child-pages and sub-child-pages in the entire directory tree |
<ReadMore />
(It won’t show anything on this page, since this page has no child-pages.)
Related
Use Related to add something that is relevant to the current topic.
Attribute | Default | Description |
---|---|---|
compact | false | Renders compact variant |
This snippet is provided by the buttons plugin
See snippets
Tip
Use Tip for, you know, tips.
Attribute | Default | Description |
---|---|---|
compact | false | Renders compact variant |
The notches on the shoulder and sleeve parts are used to help with alignment when attaching the sleeve.
Align the notches so they match
Warning
Use Warning when you want to warn the reader of potential danger or unintended side-effects.
Attribute | Default | Description |
---|---|---|
compact | false | Renders compact variant |
Please make a backup
Following these instructions will remove all your data
Take it slow
YouTube
The YouTube tag will embed YouTube videos or YouTube playlists responsively.
Attribute | Default | Description |
---|---|---|
id | ID of the YouTube video or playlist | |
playlist | false | Set this when embedding a playlist |