diff --git a/markdown/dev/guides/markdown/custom-components/en.md b/markdown/dev/guides/markdown/custom-components/en.md index 289796e2b9f..c6ea52309e2 100644 --- a/markdown/dev/guides/markdown/custom-components/en.md +++ b/markdown/dev/guides/markdown/custom-components/en.md @@ -1,158 +1,156 @@ --- -title: Custom components +title: Custom tags order: 90 --- -The way we render markdown on our websites is through the use of [MDX](https://mdxjs.com/). -This allows us to extend Markdown with our own so-called _custom components_. +The way we render markdown on our websites is through the use of +[MDX](https://mdxjs.com/). 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 components you can use in our Markdown content: +Below is a list of custom components that we support in our markdown-based +documentation, both for FreeSewing.dev as FreeSewing.org. ## Comment -**Do** try this at home - -Use a **Comment** where you want to illustrate something is a personal opinion -or tip/advice rather than the sort of general neutral voice used throughout +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. -The **Comment** component requires a `by` attribute that lists the author of the comment. +| Attribute | Default | Description | +| ---- | ------- | ----------- | +| `by` | | Name of the commenter | + + +MDX is essentially Markdown + (React) components + + ```markdown -**Do** try this at home +MDX is essentially Markdown + (React) components ``` - -## Dot - - - -```dot -rankdir="LR" -compound=true -subgraph cluster_pem { - label="I am a box" - fontsize=24 - color="oc-gray" - style="dashed" - api [label="Backend API" shape="box3d" style="dashed" color="oc-teal"] - strapi [label="Strapi" shape="box3d" style="dashed" color="oc-teal"] - db [label="Database" shape="cylinder" style="dashed" color="oc-grape"] - api -> db - strapi -> db -} - -frontend [label="FreeSewing\nFrontend" shape="component" color="oc-violet"] -user [label="User" shape="egg" color="oc-blue-2" style="filled"] -extra [label="I am an example" shape="box" color="oc-pink-2"] -dot [label="Me too!" shape="plaintext"] -i18n [label="i18n:docs" shape="signature" color="oc-red"] - -extra -> dot -extra -> i18n -dot -> db [lhead=cluster_pem dir=back] -frontend -> api -frontend -> strapi [color="oc-indigo"] -user -> frontend - -``` - -An example graph using the **Dot** custom component - - -Use **Dot** to add a [Graphviz](https://graphviz.org/) graph written in -the [Dot graph description language](https://en.wikipedia.org/wiki/DOT_\(graph_description_language\)). - -It is a way to include diagrams as code, making them easier to maintain and diff than -creating graphic files by hand. These diagrams also support dark mode, translation a and -consistent color scheme. Highly recommended when you want to clarify concepts with a little -back-of-the-napkin sketch. - - -The dot language takes some getting used to, but you can hone your skills or try it out -on [sketchviz.com](https://sketchviz.com/). - - -### Using colors - -Colors make everything prettier, but dot expects you to specify them as you would in -HTML, and juggling all those hex-codes becomes a chore. - -This custom component makes it easy to use [the open-color color -scheme](https://yeun.github.io/open-color/) by using the following color names: - -- `oc-[color]` will use the `oc-[color]-5` midtone that's suitable for both light and - dark mode. Eg: `oc-violet` -- `oc-[color]-[shade]` allows you to control the lightness. Eg: `oc-violet-200` - - -If you specify no color, graphviz will revert to `#000000` (black). This custom -component will also override that with `currentColor` so that the default also -works in dark mode - - -### Using translation - -While freesewing.dev is only available in English, you can also use this on -freesewing.org which uses translation. - -You can use the `i18n:` prefix followed by the translation key. For example -`i18n:docs` will look up the `docs` key in the default namespace. Whereas -`i18n:errors:example` will lookup the `example` keys in the `errors` namespace. + + ## Example - - Example of the snippets provided by [the buttons plugin](/reference/plugins/buttons) - +The **Example** component allows you to embed a FreeSewing code example and have it rendered in the browser. +Specifically, you should write a [draft method](/reference/api/part/draft) which will then be rendered. -Use **Example** to embed an example (a part of our `examples` pattern) that is used to -illustrate the core API documentation. Check [the examples -source code](https://github.com/freesewing/freesewing/blob/develop/designs/examples/src/index.js) for -a full list of all available parts/examples. +| Attribute | Default | Description | +| ---- | ------- | ----------- | +| `caption` | | The caption to go under the example | +| `tutorial` | `false` | Set this to show the code first, rather than the result | +| `tutorial` | `false` | Set this to show the code first, rather than the result | +| `previewFirst` | `false` | Set this to show the code first, rather than the result (same as `tutorial`) | +| `withHead` | `false` | Set this to include a head measurement (for tutorial) | +| `paperless` | `false` | Set this to enable paperless mode | +| `settings` | | A YAML string of settings to take into account | -```markdown - - Example of the snippets provided by [the buttons plugin](/reference/plugings/buttons) - + + + +```js +({ Point, points, Path, paths, part }) => { + + points.from = new Point(10, 20) + points.cp1 = new Point(40, 0) + points.cp2 = new Point(60, 40) + points.to = new Point(90, 20) + + paths.line = new Path() + .move(points.from) + .curve(points.cp1, points.cp2, points.to) + .setText("Path.curve()", "text-sm center fill-note") + + return part +} ``` + + + +````markdown + +```js +({ Point, points, Path, paths, part }) => { + + points.from = new Point(10, 20) + points.cp1 = new Point(40, 0) + points.cp2 = new Point(60, 40) + points.to = new Point(90, 20) + + paths.line = new Path() + .move(points.from) + .curve(points.cp1, points.cp2, points.to) + .setText("Path.curve()", "text-sm center fill-note") + + return part +} +``` + +```` + + + ## Fixme - -##### ToDo -- Include link to roadmap -- Fix style for text outside paragraphs - - 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 + + ```markdown ##### ToDo - Include link to roadmap - Fix style for text outside paragraphs +Show compact example ``` + + ## 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 - -Use **Note** to add something that stands out to draw attention. - +And in pink + + ```markdown ##### Also available in black This style also comes in black, which we can all agree is the superior color +And in pink ``` + + ## ReadMore @@ -167,64 +165,106 @@ It won't show anything on this page, since this page has not 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](/reference/plugins/buttons) - -Use **Related** to add something that is relevant to the current topic. - +See [snippets](/reference/snippets) + + ```markdown This snippet is provided by [the buttons plugin](/reference/plugins/buttons) +See [snippets](/reference/snippets) ``` + + + ## Tip +Use **Tip** for, you know, tips. + +| Attribute | Default | Description | +| ---- | ------- | ----------- | +| `compact` | `false` | Renders compact variant | + + + Comparing yourself to others is the fastest way to become unhappy - -Use **Tip** for, you know, tips. - +Try the veal + + ```markdown Comparing yourself to others is the fastest way to become unhappy +Try the veal ``` + + + ## Warning +Use **Warning** when you want to warn the reader for 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 - -Use **Warning** when you want to warn the reader for potential danger or unintended side-effects. - +Take it slow + + ```markdown ##### Please make a backup Following these instructions will remove all your data +Take it slow ``` + + + ## YouTube The **YouTube** components will embed YouTube videos or YouTube playlists responsively. -Embed a video: +| Attribute | Default | Description | +| ---- | ------- | ----------- | +| `id` | | ID of the YouTube video or playlist | +| `playlist` | `false` | Set this when embedding a playlist | + + +### Video - +### Playlist + + + ```markdown +### Video -``` - -Embed a playlist: - - - -```md +### Playlist ``` + +