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.

Summary and Availability

This is a summary of the available custom tags and where each tag can be used.

• sde tags can be used in the standalone development environment (provided by the new-design package).
• dev and org tags can be used on the freesewing.dev and freesewing.org sites, respectively.
• For convenience, tags with similar functionality have been grouped together.

Text popouts

These are markdown tags used to display text in a colored popout box, to make the text stand out and to quickly convey what type of information is being presented.

Tag	sde	dev	org
Comment	X	X	X
Fixme	X	X	X
Link	X	X	X
Note	X	X	X
Related	X	X	X
Tip	X	X	X
Tldr	X	X	X
Warning	X	X	X

Features and Formatting

These tags provide special features or ways to format content.

Tag	sde	dev	org
ControlTip		X	X
DocsTitle		X	X
DocsLink		X	X
Example		X	X
Legend			X*
MeasieImage			X*
(Mermaid)		X	X
Method		X
StatusCode		X
Tab		X	X
Tabs		X	X
Youtube		X	X

Documentation Generators

These tags generate documentation-related content related to designs and documentation files. This prevents the need to write and edit the documentation manually, making it easier to write and to maintain when changes occur.

Tag	sde	dev	org
DesignInfo			X*
DesignMeasurements			X*
DesignOptions			X*
ReadMore	X	X	X

---

Details

All custom tags are listed alphabetically below.

Comment

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

Attribute	Required?	Default	Description
by	yes		Name of the commenter
hideable		false	Allows popout to be hidden

ControlTip

The ControlTip tag provides a popout box containing pre-written, formatted text describing the User Experience account setting and explaining what it does.

DesignInfo

DesignInfo generates a detailed web page for a given FreeSewing design with information including line drawings, example photos, required measurements, design options, and links to documentation.

Attribute	Required?	Default	Description
design	yes		Name of the design
docs		false	Generates content suitable for a documentation page

DesignMeasurements

DesignMeasurements generates a list of required and optional measurements for a given FreeSewing design.

Attribute	Required?	Default	Description
design	yes		Name of the design

DesignOptions

DesignOptions generates a list of design options and settings for a given FreeSewing design.

Attribute	Required?	Default	Description
design	yes		Name of the design

DocsLink

The DocsLink tag creates a formatted link from a given slug (a relative URL path). It also looks up the title of the linked web page and uses it as the link text.

Attribute	Required?	Default	Description
slug	yes		Relative path for the link

DocsTitle

The DocsTitle tag looks up the title of a web page from a given slug (a relative URL path) and provides the title as formatted text.

Attribute	Required?	Default	Description
slug	yes		Relative path of the link
className			CSS classes to style the text
format		defaultFormater	Formatter used to format the text

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	Required?	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	Required?	Default	Description
compact		false	Renders compact variant
hideable		false	Allows popout to be hidden

Legend

The Legend tag is used to display parts from a pattern of the Legend design (a non-public design in the FreeSewing repository created to provide examples of pattern features).

Attribute	Required?	Default	Description
part	yes		The Legend part to display

Link

Use Link for URLs.

Attribute	Required?	Default	Description
compact		false	Renders compact variant
hideable		false	Allows popout to be hidden

MeasieImage

MeasieImage will show images of a FreeSewing measurement. The name of the directory in which the tag is used is the measurement which will be shown.

(Mermaid)

There is no actual “Mermaid” custom tag. However, by using a fenced code block and specifying the mermaid language, you can generate Mermaid diagrams. Like this:

Method

Method is used to format HTTP methods.

Attribute	Required?	Default	Description
get		false	Display the HTTP GET method
post		false	Display the HTTP POST method
put		false	Display the HTTP PUT method
delete		false	Display the HTTP DELETE method

Note

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

Attribute	Required?	Default	Description
compact		false	Renders compact variant
hideable		false	Allows popout to be hidden

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	Required?	Default	Description
asMenu		false	Start from the parent directory
depth		99	Maximum levels to recurse
recurse		false	Include all child-pages and sub-child-pages in the entire directory tree
root		false	Start from the root directory

Related

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

Attribute	Required?	Default	Description
compact		false	Renders compact variant
hideable		false	Allows popout to be hidden

StatusCode

StatusCode is used to format HTTP response status codes.

Attribute	Required?	Default	Description
status	yes		The HTTP response status code to format

Tab

Tabs and Tab tags are used to present content in a tabbed view. This is a view where only the active tab content is shown, with content in other tabs hidden. Selecting a different tab shows its contents while hiding the others.

The Tab tag is used to add content for a tab.

Tabs

Tabs and Tab tags are used to present content in a tabbed view. This is a view where only the active tab content is shown, with content in other tabs hidden. Selecting a different tab shows its contents while hiding the others.

The Tabs tag is used to set up the tabbed view. It specifies how many tabs are in the view and what their names are.

Attribute	Required?	Default	Description
tabs	yes		Comma-separated list of tab names

Tip

Use Tip for, you know, tips.

Attribute	Required?	Default	Description
compact		false	Renders compact variant
hideable		false	Allows popout to be hidden

Tldr

”TL;DR” stands for “Too long; didn’t read”, and the Tldr tag used to provide a short summary for readers who might not want to read the full text.

Attribute	Required?	Default	Description
compact		false	Renders compact variant
hideable		false	Allows popout to be hidden

Warning

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

Attribute	Required?	Default	Description
compact		false	Renders compact variant
hideable		false	Allows popout to be hidden

YouTube

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

Attribute	Required?	Default	Description
id	yes		ID of the YouTube video or playlist
playlist		false	Set this when embedding a playlist