diff --git a/markdown/dev/guides/markdown/code-blocks/en.md b/markdown/dev/guides/markdown/code-blocks/en.md index fd150ad2b2c..3f26926c81e 100644 --- a/markdown/dev/guides/markdown/code-blocks/en.md +++ b/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 diff --git a/markdown/dev/guides/markdown/custom-components/en.md b/markdown/dev/guides/markdown/custom-components/en.md index d0e462e3304..be1de34bf67 100644 --- a/markdown/dev/guides/markdown/custom-components/en.md +++ b/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: - +## Example + + Example of the snippets provided by [the buttons plugin](/reference/plugings/buttons) + + +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 of the snippets provided by [the buttons plugin](/reference/plugings/buttons) + +``` + +## 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 +our documentation. + +The **Comment** component requires a `by` attribute that lists the author of the comment. + +```markdown +**Do** try this at home +``` + + +## 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. + +```markdown + +##### ToDo +- Include link to roadmap +- Fix style for text outside paragraphs + +``` + + +## Note + + +##### 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. + +```markdown + +##### Also available in black +This style also comes in black, which we can all agree is the superior color + +``` + +## 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 + +``` + +It won't show anything on this page, since this page has not child-pages. + +## Related + + This snippet is provided by [the buttons plugin](/reference/plugins/buttons) + + +Use **Related** to add something that is relevant to the current topic. + +```markdown + + This snippet is provided by [the buttons plugin](/reference/plugins/buttons) + +``` + +## 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 +Use **Tip** for, you know, tips. + +```markdown + + Comparing yourself to others is the fastest way to become unhappy + +``` + +## Warning + + ##### 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. + +```markdown + + ##### Please make a backup + Following these instructions will remove all your data + +``` + +## YouTube + +The **YouTube** components will embed YouTube videos or YouTube playlists responsively. + +Embed a video: + + + +```markdown + +``` + +Embed a playlist: + + + +```md + +``` + + + diff --git a/markdown/dev/guides/markdown/custom-components/example/en.md b/markdown/dev/guides/markdown/custom-components/example/en.md deleted file mode 100644 index bd08b855710..00000000000 --- a/markdown/dev/guides/markdown/custom-components/example/en.md +++ /dev/null @@ -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 - -``` - - diff --git a/markdown/dev/guides/markdown/custom-components/fixme/en.md b/markdown/dev/guides/markdown/custom-components/fixme/en.md deleted file mode 100644 index c480cb071d8..00000000000 --- a/markdown/dev/guides/markdown/custom-components/fixme/en.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Fixme -order: 40 ---- - -```md - - -##### I am a FIXME -I indicate that something needs work or improvement - - -``` - - - -##### I am a FIXME -I indicate that something needs work or improvement - - - diff --git a/markdown/dev/guides/markdown/custom-components/hashtag/en.md b/markdown/dev/guides/markdown/custom-components/hashtag/en.md deleted file mode 100644 index a806ec5f041..00000000000 --- a/markdown/dev/guides/markdown/custom-components/hashtag/en.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Hashtag -order: 60 ---- - -Typically used on our community pages: - -```md - -``` - -Adds our _community_ font and color: - - - - diff --git a/markdown/dev/guides/markdown/custom-components/note/en.md b/markdown/dev/guides/markdown/custom-components/note/en.md deleted file mode 100644 index 1860590b57a..00000000000 --- a/markdown/dev/guides/markdown/custom-components/note/en.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Note -order: 10 ---- - -```md - - -##### I am a note -I point out things - - -``` - - - -##### I am a note -I point out things - - diff --git a/markdown/dev/guides/markdown/custom-components/readmore/en.md b/markdown/dev/guides/markdown/custom-components/readmore/en.md deleted file mode 100644 index bae52c2d684..00000000000 --- a/markdown/dev/guides/markdown/custom-components/readmore/en.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: ReadMore -order: 70 ---- - -This component will list child pages of the current page. - -##### Default - -```md - -``` - - -##### With custom title - -You can customize the title by passing a `title` prop: - -```md - -``` - - -##### As a list - -The most common use of this component is by passing the `list` -prop which returns the pages as a list: - -```md - -``` - - -##### As a recursive list - -You can make the list recursive with the `recurse` prop (which implies the `list` prop): - -```md - -``` - - diff --git a/markdown/dev/guides/markdown/custom-components/readmore/example-1/en.md b/markdown/dev/guides/markdown/custom-components/readmore/example-1/en.md deleted file mode 100644 index 244f957a73d..00000000000 --- a/markdown/dev/guides/markdown/custom-components/readmore/example-1/en.md +++ /dev/null @@ -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/). diff --git a/markdown/dev/guides/markdown/custom-components/readmore/example-2/en.md b/markdown/dev/guides/markdown/custom-components/readmore/example-2/en.md deleted file mode 100644 index 9bb169388da..00000000000 --- a/markdown/dev/guides/markdown/custom-components/readmore/example-2/en.md +++ /dev/null @@ -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/). diff --git a/markdown/dev/guides/markdown/custom-components/readmore/example-2/sub-example-2-1/en.md b/markdown/dev/guides/markdown/custom-components/readmore/example-2/sub-example-2-1/en.md deleted file mode 100644 index 13b41feb4eb..00000000000 --- a/markdown/dev/guides/markdown/custom-components/readmore/example-2/sub-example-2-1/en.md +++ /dev/null @@ -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/). diff --git a/markdown/dev/guides/markdown/custom-components/readmore/example-2/sub-example-2-2/en.md b/markdown/dev/guides/markdown/custom-components/readmore/example-2/sub-example-2-2/en.md deleted file mode 100644 index 8791ecacd22..00000000000 --- a/markdown/dev/guides/markdown/custom-components/readmore/example-2/sub-example-2-2/en.md +++ /dev/null @@ -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/). diff --git a/markdown/dev/guides/markdown/custom-components/tip/en.md b/markdown/dev/guides/markdown/custom-components/tip/en.md deleted file mode 100644 index 63ae70ca1d8..00000000000 --- a/markdown/dev/guides/markdown/custom-components/tip/en.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Tip -order: 20 ---- - -```md - - -##### I am a tip -I give great advice - - -``` - - - -##### I am a tip -I give great advice - - - diff --git a/markdown/dev/guides/markdown/custom-components/warning/en.md b/markdown/dev/guides/markdown/custom-components/warning/en.md deleted file mode 100644 index 49688d430f4..00000000000 --- a/markdown/dev/guides/markdown/custom-components/warning/en.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Warning -order: 30 ---- - -```md - - -##### I am a warning -Ignore me at your own peril - - -``` - - - -##### I am a warning -Ignore me at your own peril - - - diff --git a/markdown/dev/guides/markdown/custom-components/youtube/en.md b/markdown/dev/guides/markdown/custom-components/youtube/en.md deleted file mode 100644 index 3d5e0406137..00000000000 --- a/markdown/dev/guides/markdown/custom-components/youtube/en.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: YouTube -order: 50 ---- - -This components will embed videos and playlists responsively. - -##### Video - -Embed a single video: - -```md - -``` - - - -##### Playlist - -Embed a playlist: - -```md - -``` - - - diff --git a/markdown/dev/guides/markdown/images/en.md b/markdown/dev/guides/markdown/images/en.md index b6d78b838bf..c87921b59a2 100644 --- a/markdown/dev/guides/markdown/images/en.md +++ b/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. -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 -![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") +##### 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. diff --git a/markdown/dev/guides/markdown/links/en.md b/markdown/dev/guides/markdown/links/en.md index 501e3f20079..fdc6416fdc9 100644 --- a/markdown/dev/guides/markdown/links/en.md +++ b/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 +