fix(markdown): Updated mdx component docs
This commit is contained in:
Joost De Cock
parent
1ba5b564eb
commit
65d72ad66e
16 changed files with 178 additions and 225 deletions
|
|
@ -9,7 +9,7 @@ You can make these look pretty by using a code block.
|
|||
|
||||
The basic use is to wrap your code in three backtick characters on a line:
|
||||
|
||||
````
|
||||
````markdown
|
||||
```
|
||||
let me = 'you'
|
||||
```
|
||||
|
|
@ -17,14 +17,14 @@ let me = 'you'
|
|||
|
||||
Gives you:
|
||||
|
||||
```
|
||||
```text
|
||||
let me = 'you'
|
||||
```
|
||||
|
||||
This is a generic code block. But we also support syntax highlighting.
|
||||
To do so, add the language specifier after the opening backticks:
|
||||
|
||||
````
|
||||
````markdown
|
||||
```js
|
||||
let me = 'you'
|
||||
```
|
||||
|
|
@ -39,15 +39,13 @@ let me = 'you'
|
|||
The following language codes are supported:
|
||||
|
||||
- `js` for Javascript code
|
||||
- `md` for Markdown
|
||||
- `markdown` for Markdown
|
||||
- `html` for HTML
|
||||
- `svg` for SVG
|
||||
- `bash` for Bash or shell scripts
|
||||
- `mdx` for MDX
|
||||
- `jsx` for JSX
|
||||
- `json` for JSON
|
||||
- `js-error` for a Javascript error
|
||||
- `js-trace` for a Javascript stack trace
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -11,13 +11,145 @@ typically require a lot more complexity.
|
|||
|
||||
Below is a list of custom components you can use in our Markdown content:
|
||||
|
||||
<ReadMore list />
|
||||
## Example
|
||||
|
||||
<Example part="plugin_buttons">
|
||||
Example of the snippets provided by [the buttons plugin](/reference/plugings/buttons)
|
||||
</Example>
|
||||
|
||||
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/packages/examples/src/index.js) for
|
||||
a full list of all available parts/examples.
|
||||
|
||||
```markdown
|
||||
<Example part="plugin_buttons">
|
||||
Example of the snippets provided by [the buttons plugin](/reference/plugings/buttons)
|
||||
</Example>
|
||||
```
|
||||
|
||||
## Comment
|
||||
|
||||
<Comment by="joost">**Do** try this at home</Comment>
|
||||
|
||||
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.
|
||||
|
||||
The **Comment** component requires a `by` attribute that lists the author of the comment.
|
||||
|
||||
```markdown
|
||||
<Comment by="joost">**Do** try this at home</Comment>
|
||||
```
|
||||
|
||||
|
||||
## 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
|
||||
or can't fix it now.
|
||||
|
||||
```markdown
|
||||
<Fixme>
|
||||
##### ToDo
|
||||
- Include link to roadmap
|
||||
- Fix style for text outside paragraphs
|
||||
</Fixme>
|
||||
```
|
||||
|
||||
|
||||
## Note
|
||||
|
||||
<Note>
|
||||
##### Also available in black
|
||||
This style also comes in black, which we can all agree is the superior color
|
||||
</Note>
|
||||
|
||||
Use **Note** to add something that stands out to draw attention.
|
||||
|
||||
```markdown
|
||||
<Note>
|
||||
##### Also available in black
|
||||
This style also comes in black, which we can all agree is the superior color
|
||||
</Note>
|
||||
```
|
||||
|
||||
## ReadMore
|
||||
|
||||
The ReadMore component allows you to insert a list of child-pages.
|
||||
It's typically used on overview pages, such as out [markdown guide](/guides/markdown) page.
|
||||
|
||||
```markdown
|
||||
<ReadMore />
|
||||
```
|
||||
|
||||
It won't show anything on this page, since this page has not child-pages.
|
||||
|
||||
## Related
|
||||
<Related>
|
||||
This snippet is provided by [the buttons plugin](/reference/plugins/buttons)
|
||||
</Related>
|
||||
|
||||
Use **Related** to add something that is relevant to the current topic.
|
||||
|
||||
```markdown
|
||||
<Related>
|
||||
This snippet is provided by [the buttons plugin](/reference/plugins/buttons)
|
||||
</Related>
|
||||
```
|
||||
|
||||
## Tip
|
||||
<Tip>
|
||||
|
||||
Keep in mind that if you place content inside a custom component, you need to leave an empty
|
||||
line at the start and finish. If you don't, the custom component will still work, but the
|
||||
content inside of it will not be parsed as Markdown.
|
||||
|
||||
Comparing yourself to others is the fastest way to become unhappy
|
||||
</Tip>
|
||||
|
||||
Use **Tip** for, you know, tips.
|
||||
|
||||
```markdown
|
||||
<Tip>
|
||||
Comparing yourself to others is the fastest way to become unhappy
|
||||
</Tip>
|
||||
```
|
||||
|
||||
## Warning
|
||||
<Warning>
|
||||
##### Please make a backup
|
||||
Following these instructions will remove all your data
|
||||
</Warning>
|
||||
|
||||
Use **Warning** when you want to warn the reader for potential danger or unintended side-effects.
|
||||
|
||||
```markdown
|
||||
<Warning>
|
||||
##### Please make a backup
|
||||
Following these instructions will remove all your data
|
||||
</Warning>
|
||||
```
|
||||
|
||||
## YouTube
|
||||
|
||||
The **YouTube** components will embed YouTube videos or YouTube playlists responsively.
|
||||
|
||||
Embed a video:
|
||||
|
||||
<YouTube id='Rz6ShSftDlI' />
|
||||
|
||||
```markdown
|
||||
<YouTube id='Rz6ShSftDlI' />
|
||||
```
|
||||
|
||||
Embed a playlist:
|
||||
|
||||
<YouTube id='PL1gv5yv3DoZOFSXz7yydeV1H8m6pfwstn' playlist />
|
||||
|
||||
```md
|
||||
<YouTube id='PL1gv5yv3DoZOFSXz7yydeV1H8m6pfwstn' playlist />
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -1,21 +0,0 @@
|
|||
---
|
||||
title: Example
|
||||
order: 90
|
||||
---
|
||||
|
||||
Embeds an example -- a part of our `example` pattern that is used to
|
||||
illustrate the core API documentation.
|
||||
|
||||
This custom component is rather advanced, and its exact parameters
|
||||
and use is not fully covered below. It's good to know it exists though.
|
||||
And if you want to use it, reach out on Discord to some of our more
|
||||
experienced documentation writers.
|
||||
|
||||
```md
|
||||
<Example
|
||||
part="path_attr"
|
||||
caption="Example of the Example custom component"
|
||||
/>
|
||||
```
|
||||
|
||||
<Example part="path_attr" caption="Example of the Example custom component" />
|
||||
|
|
@ -1,21 +0,0 @@
|
|||
---
|
||||
title: Fixme
|
||||
order: 40
|
||||
---
|
||||
|
||||
```md
|
||||
<Fixme>
|
||||
|
||||
##### I am a FIXME
|
||||
I indicate that something needs work or improvement
|
||||
|
||||
</Fixme>
|
||||
```
|
||||
|
||||
<Fixme>
|
||||
|
||||
##### I am a FIXME
|
||||
I indicate that something needs work or improvement
|
||||
|
||||
</Fixme>
|
||||
|
||||
|
|
@ -1,16 +0,0 @@
|
|||
---
|
||||
title: Hashtag
|
||||
order: 60
|
||||
---
|
||||
|
||||
Typically used on our community pages:
|
||||
|
||||
```md
|
||||
<Hashtag tag='WeAreFreeSewing' />
|
||||
```
|
||||
|
||||
Adds our _community_ font and color:
|
||||
|
||||
<Hashtag tag='WeAreFreeSewing' />
|
||||
|
||||
|
||||
|
|
@ -1,20 +0,0 @@
|
|||
---
|
||||
title: Note
|
||||
order: 10
|
||||
---
|
||||
|
||||
```md
|
||||
<Note>
|
||||
|
||||
##### I am a note
|
||||
I point out things
|
||||
|
||||
</Note>
|
||||
```
|
||||
|
||||
<Note>
|
||||
|
||||
##### I am a note
|
||||
I point out things
|
||||
|
||||
</Note>
|
||||
|
|
@ -1,42 +0,0 @@
|
|||
---
|
||||
title: ReadMore
|
||||
order: 70
|
||||
---
|
||||
|
||||
This component will list child pages of the current page.
|
||||
|
||||
##### Default
|
||||
|
||||
```md
|
||||
<ReadMore />
|
||||
```
|
||||
<ReadMore />
|
||||
|
||||
##### With custom title
|
||||
|
||||
You can customize the title by passing a `title` prop:
|
||||
|
||||
```md
|
||||
<ReadMore title='Example pages'/>
|
||||
```
|
||||
<ReadMore title='Example pages'/>
|
||||
|
||||
##### As a list
|
||||
|
||||
The most common use of this component is by passing the `list`
|
||||
prop which returns the pages as a list:
|
||||
|
||||
```md
|
||||
<ReadMore list />
|
||||
```
|
||||
<ReadMore list />
|
||||
|
||||
##### As a recursive list
|
||||
|
||||
You can make the list recursive with the `recurse` prop (which implies the `list` prop):
|
||||
|
||||
```md
|
||||
<ReadMore recurse />
|
||||
```
|
||||
|
||||
<ReadMore recurse />
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
---
|
||||
title: Example page 1
|
||||
---
|
||||
|
||||
This page is here to illustrate the use of [the `ReadMore` custom component](/editors/markdown/custom-components/readmore/).
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
---
|
||||
title: Example page 2
|
||||
---
|
||||
|
||||
This page is here to illustrate the use of [the `ReadMore` custom component](/editors/markdown/custom-components/readmore/).
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
---
|
||||
title: Sub-example page 1
|
||||
---
|
||||
|
||||
This page is here to illustrate the use of [the `ReadMore` custom component](/editors/markdown/custom-components/readmore/).
|
||||
|
|
@ -1,5 +0,0 @@
|
|||
---
|
||||
title: Sub-example page 2
|
||||
---
|
||||
|
||||
This page is here to illustrate the use of [the `ReadMore` custom component](/editors/markdown/custom-components/readmore/).
|
||||
|
|
@ -1,21 +0,0 @@
|
|||
---
|
||||
title: Tip
|
||||
order: 20
|
||||
---
|
||||
|
||||
```md
|
||||
<Tip>
|
||||
|
||||
##### I am a tip
|
||||
I give great advice
|
||||
|
||||
</Tip>
|
||||
```
|
||||
|
||||
<Tip>
|
||||
|
||||
##### I am a tip
|
||||
I give great advice
|
||||
|
||||
</Tip>
|
||||
|
||||
|
|
@ -1,21 +0,0 @@
|
|||
---
|
||||
title: Warning
|
||||
order: 30
|
||||
---
|
||||
|
||||
```md
|
||||
<Warning>
|
||||
|
||||
##### I am a warning
|
||||
Ignore me at your own peril
|
||||
|
||||
</Warning>
|
||||
```
|
||||
|
||||
<Warning>
|
||||
|
||||
##### I am a warning
|
||||
Ignore me at your own peril
|
||||
|
||||
</Warning>
|
||||
|
||||
|
|
@ -1,27 +0,0 @@
|
|||
---
|
||||
title: YouTube
|
||||
order: 50
|
||||
---
|
||||
|
||||
This components will embed videos and playlists responsively.
|
||||
|
||||
##### Video
|
||||
|
||||
Embed a single video:
|
||||
|
||||
```md
|
||||
<YouTube id='Rz6ShSftDlI' />
|
||||
```
|
||||
|
||||
<YouTube id='Rz6ShSftDlI' />
|
||||
|
||||
##### Playlist
|
||||
|
||||
Embed a playlist:
|
||||
|
||||
```md
|
||||
<YouTube id='RDRz6ShSftDlI' playlist />
|
||||
```
|
||||
|
||||
<YouTube id='RDRz6ShSftDlI' playlist />
|
||||
|
||||
|
|
@ -3,17 +3,23 @@ title: Images
|
|||
order: 70
|
||||
---
|
||||
|
||||
Images are like links, just prefix them with an exclamation mark.
|
||||
The part between square brackets is the image caption or alt-text.
|
||||
Images are like links, but you prefix them with an exclamation mark.
|
||||
|
||||
The part between square brackets is the image alt text.
|
||||
|
||||
Between the curly brackets you place the location of the image file
|
||||
followed by a space and the image title between quotes.
|
||||
|
||||
```md
|
||||
|
||||
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
<Tip>
|
||||
|
||||
##### Images go in the same folder as your markdown file
|
||||
|
||||
The convention is to always place your images in the same folder as the
|
||||
text where you are including the image. That way, you just need to specify
|
||||
the image name, and not the path to its location.
|
||||
|
|
|
|||
|
|
@ -10,3 +10,29 @@ Links combine square brackets for the link text with round brackets for the dest
|
|||
```
|
||||
[Like this](https://freesewing.org)
|
||||
|
||||
An alternative notation allows you to include the links as such:
|
||||
|
||||
```md
|
||||
See [the reference documentation][1] on [freesewing.dev][2]
|
||||
|
||||
[1]: https://freesewing.dev/reference
|
||||
[2]: https://freesewing.dev/reference
|
||||
```
|
||||
|
||||
See [the reference documentation][1] on [freesewing.dev][2]
|
||||
|
||||
[1]: https://freesewing.dev/reference
|
||||
[2]: https://freesewing.dev/reference
|
||||
|
||||
You don't have to use numbers, but can also use named references.
|
||||
|
||||
```md
|
||||
We moved the markdown content to [our monorepo][monorepo]
|
||||
|
||||
[monorepo]: https://github.com/freesewing/freesewing
|
||||
```
|
||||
|
||||
We moved the markdown content to [our monorepo][monorepo]
|
||||
|
||||
[monorepo]: https://github.com/freesewing/freesewing
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue