fix(markdown): Updated mdx component docs

markdown/dev/guides/markdown/code-blocks/en.md

@@ -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
 
 
 

markdown/dev/guides/markdown/custom-components/en.md

@@ -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>
-
+  Comparing yourself to others is the fastest way to become unhappy
-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.
-
 </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 />
+```
+  
+
+

markdown/dev/guides/markdown/custom-components/example/en.md

@@ -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" />

markdown/dev/guides/markdown/custom-components/fixme/en.md

@@ -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>
-

markdown/dev/guides/markdown/custom-components/hashtag/en.md

@@ -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' />
-
-

markdown/dev/guides/markdown/custom-components/note/en.md

@@ -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>

markdown/dev/guides/markdown/custom-components/readmore/en.md

@@ -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 />

markdown/dev/guides/markdown/custom-components/readmore/example-1/en.md

@@ -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/).

markdown/dev/guides/markdown/custom-components/readmore/example-2/en.md

@@ -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/).

markdown/dev/guides/markdown/custom-components/readmore/example-2/sub-example-2-1/en.md

@@ -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/).

markdown/dev/guides/markdown/custom-components/readmore/example-2/sub-example-2-2/en.md

@@ -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/).

markdown/dev/guides/markdown/custom-components/tip/en.md

@@ -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>
-

markdown/dev/guides/markdown/custom-components/warning/en.md

@@ -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>
-

markdown/dev/guides/markdown/custom-components/youtube/en.md

@@ -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 />
-

markdown/dev/guides/markdown/images/en.md

@@ -3,17 +3,23 @@ title: Images
 order: 70
 ---
 
-Images are like links, just prefix them with an exclamation mark.
+Images are like links, but you prefix them with an exclamation mark.
-The part between square brackets is the image caption or alt-text.
+
+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
-![This is the alt-text & title](image.jpg)
+![This is the alt text](image.jpg "This is the image title")
 ```
 
-![This is the alt text & title](image.jpg)
+![This is the alt text & title](image.jpg "This is the image title")
 
 <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.

markdown/dev/guides/markdown/links/en.md

@@ -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
+