VSinerva/freesewing
1
0
Fork 0
Code Activity

chore(markdown): Updated mdx components docs for v3

Browse source
This commit is contained in:
Joost De Cock 2022-10-16 22:59:30 +02:00
parent 3e7a815edf
commit 4a9d4ce76f
1 changed files with 165 additions and 125 deletions
Download patch file Download diff file Expand all files Collapse all files

290
markdown/dev/guides/markdown/custom-components/en.md
View file

@ -1,158 +1,156 @@
--- ---
title: Custom components title: Custom tags
order: 90 order: 90
--- ---
The way we render markdown on our websites is through the use of [MDX](https://mdxjs.com/). The way we render markdown on our websites is through the use of
This allows us to extend Markdown with our own so-called _custom components_. [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 Such custom components allow us to put things in Markdown content that would
typically require a lot more complexity. 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 ## Comment
<Comment by="joost">**Do** try this at home</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
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
our documentation. our documentation.
The **Comment** component requires a `by` attribute that lists the author of the comment. | Attribute | Default | Description |
| ---- | ------- | ----------- |
| `by` | | Name of the commenter |
<Tabs tabs="example, markdown">
<Tab>
<Comment by="joost">MDX is essentially Markdown + (React) components</Comment>
</Tab>
<Tab>
```markdown ```markdown
<Comment by="joost">**Do** try this at home</Comment> <Comment by="joost">MDX is essentially Markdown + (React) components</Comment>
``` ```
</Tab>
## Dot </Tabs>
<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
</Dot>
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.
<Tip>
The dot language takes some getting used to, but you can hone your skills or try it out
on [sketchviz.com](https://sketchviz.com/).
</Tip>
### 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`
<Note>
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
</Note>
### 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
<Example part="plugin_buttons"> The **Example** component allows you to embed a FreeSewing code example and have it rendered in the browser.
Example of the snippets provided by [the buttons plugin](/reference/plugins/buttons) Specifically, you should write a [draft method](/reference/api/part/draft) which will then be rendered.
</Example>
Use **Example** to embed an example (a part of our `examples` pattern) that is used to | Attribute | Default | Description |
illustrate the core API documentation. Check [the examples | ---- | ------- | ----------- |
source code](https://github.com/freesewing/freesewing/blob/develop/designs/examples/src/index.js) for | `caption` | | The caption to go under the example |
a full list of all available parts/examples. | `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 <Tabs tabs="example, markdown">
<Example part="plugin_buttons"> <Tab>
Example of the snippets provided by [the buttons plugin](/reference/plugings/buttons) <Example caption="Example of the Path.curve() method">
</Example> ```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
}
``` ```
</Example>
</Tab>
<Tab>
````markdown
<Example caption="Example of the Path.curve() method">
```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
}
```
</Example>
````
</Tab>
</Tabs>
## Fixme ## Fixme
<Fixme>
##### ToDo
- Include link to roadmap
- Fix style for text outside paragraphs
</Fixme>
Use **Fixme** to indicate something needs attention/work but you don't have time Use **Fixme** to indicate something needs attention/work but you don't have time
or can't fix it now. or can't fix it now.
| Attribute | Default | Description |
| --------- | ------- | ----------- |
| `compact` | `false` | Renders compact variant |
<Tabs tabs="example, markdown">
<Tab>
<Fixme>
##### ToDo
- Include link to roadmap
- Fix style for text outside paragraphs
</Fixme>
<Fixme compact>Show compact example</Fixme>
</Tab>
<Tab>
```markdown ```markdown
<Fixme> <Fixme>
##### ToDo ##### ToDo
- Include link to roadmap - Include link to roadmap
- Fix style for text outside paragraphs - Fix style for text outside paragraphs
</Fixme> </Fixme>
<Fixme compact>Show compact example</Fixme>
``` ```
</Tab>
</Tabs>
## Note ## Note
Use **Note** to add something that stands out to draw attention.
| Attribute | Default | Description |
| ---- | ------- | ----------- |
| `compact` | `false` | Renders compact variant |
<Tabs tabs="example, markdown">
<Tab>
<Note> <Note>
##### Also available in black ##### Also available in black
This style also comes in black, which we can all agree is the superior color This style also comes in black, which we can all agree is the superior color
</Note> </Note>
<Note compact>And in pink</Note>
Use **Note** to add something that stands out to draw attention. </Tab>
<Tab>
```markdown ```markdown
<Note> <Note>
##### Also available in black ##### Also available in black
This style also comes in black, which we can all agree is the superior color This style also comes in black, which we can all agree is the superior color
</Note> </Note>
<Note compact>And in pink</Note>
``` ```
</Tab>
</Tabs>
## ReadMore ## ReadMore
@ -167,64 +165,106 @@ It won't show anything on this page, since this page has not child-pages.
## Related ## Related
Use **Related** to add something that is relevant to the current topic.
| Attribute | Default | Description |
| ---- | ------- | ----------- |
| `compact` | `false` | Renders compact variant |
<Tabs tabs="example, markdown">
<Tab>
<Related> <Related>
This snippet is provided by [the buttons plugin](/reference/plugins/buttons) This snippet is provided by [the buttons plugin](/reference/plugins/buttons)
</Related> </Related>
<Related compact>See [snippets](/reference/snippets)</Related>
Use **Related** to add something that is relevant to the current topic. </Tab>
<Tab>
```markdown ```markdown
<Related> <Related>
This snippet is provided by [the buttons plugin](/reference/plugins/buttons) This snippet is provided by [the buttons plugin](/reference/plugins/buttons)
</Related> </Related>
<Related compact>See [snippets](/reference/snippets)</Related>
``` ```
</Tab>
</Tabs>
## Tip ## Tip
Use **Tip** for, you know, tips.
| Attribute | Default | Description |
| ---- | ------- | ----------- |
| `compact` | `false` | Renders compact variant |
<Tabs tabs="example, markdown">
<Tab>
<Tip> <Tip>
Comparing yourself to others is the fastest way to become unhappy Comparing yourself to others is the fastest way to become unhappy
</Tip> </Tip>
<Tip compact>Try the veal</Tip>
Use **Tip** for, you know, tips. </Tab>
<Tab>
```markdown ```markdown
<Tip> <Tip>
Comparing yourself to others is the fastest way to become unhappy Comparing yourself to others is the fastest way to become unhappy
</Tip> </Tip>
<Tip compact>Try the veal</Tip>
``` ```
</Tab>
</Tabs>
## Warning ## 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 |
<Tabs tabs="example, markdown">
<Tab>
<Warning> <Warning>
##### Please make a backup ##### Please make a backup
Following these instructions will remove all your data Following these instructions will remove all your data
</Warning> </Warning>
<Warning compact>Take it slow</Warning>
Use **Warning** when you want to warn the reader for potential danger or unintended side-effects. </Tab>
<Tab>
```markdown ```markdown
<Warning> <Warning>
##### Please make a backup ##### Please make a backup
Following these instructions will remove all your data Following these instructions will remove all your data
</Warning> </Warning>
<Warning compact>Take it slow</Warning>
``` ```
</Tab>
</Tabs>
## YouTube ## YouTube
The **YouTube** components will embed YouTube videos or YouTube playlists responsively. 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 |
<Tabs tabs="example, markdown">
<Tab>
### Video
<YouTube id='Rz6ShSftDlI' /> <YouTube id='Rz6ShSftDlI' />
### Playlist
<YouTube id='PL1gv5yv3DoZOFSXz7yydeV1H8m6pfwstn' playlist />
</Tab>
<Tab>
```markdown ```markdown
### Video
<YouTube id='Rz6ShSftDlI' /> <YouTube id='Rz6ShSftDlI' />
``` ### Playlist
Embed a playlist:
<YouTube id='PL1gv5yv3DoZOFSXz7yydeV1H8m6pfwstn' playlist />
```md
<YouTube id='PL1gv5yv3DoZOFSXz7yydeV1H8m6pfwstn' playlist /> <YouTube id='PL1gv5yv3DoZOFSXz7yydeV1H8m6pfwstn' playlist />
``` ```
</Tab>
</Tabs>