From e57d1ce6b8def490938b4efa3a05d850abd2ca4d Mon Sep 17 00:00:00 2001 From: about-code <6525873+about-code@users.noreply.github.com> Date: Sat, 20 Feb 2021 16:23:18 +0100 Subject: [PATCH] doc: Wording --- README.md | 10 +++++----- demo/conceptual-layers.md | 9 ++++++--- doc/conceptual-layers.md | 14 +++++++++----- md/README.md | 11 ++++++----- 4 files changed, 26 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 79f3ba40..f0051e93 100644 --- a/README.md +++ b/README.md @@ -696,7 +696,9 @@ key: This is a frontmatter --- ``` -Without special support for it our Markdown parser ([remark]) will recognise the line of trailing dashes as Markdown syntax for a *heading*. To make it aware that they contribute to syntax for a *frontmatter* we need to enhance the parser. **Since v5.0.0** we have opened [glossarify-md] to the [remark plug-in ecosystem][remark-plugins] and its extensive support of additional syntaxes and tools: +Without special support for it our Markdown parser ([remark]) will interpret the line of trailing dashes as Markdown syntax for a *heading*. To make it aware that they contribute to syntax for a *frontmatter* we need to enhance the parser. **Since v5.0.0** we have opened [glossarify-md] to the [remark plug-in ecosystem][remark-plugins] and its extensive support of additional syntaxes and tools: + +> **Note:** glossarify-md must not be held responsible for issues arising due to installing and using additional plug-ins. *Add this to your glossarify-md.conf.json* @@ -727,16 +729,14 @@ and make remark load the plug-in by adding to your *remark.conf.json*: } ``` -> **Note:** glossarify-md must not be held responsible for issues arising due to installing and using additional plug-ins. - `remark.conf.json` follows the [unified configuration][unified-config] schema: - `remark-frontmatter` must be the name of the npm package you installed before. - Any properties of the object are specific to the plug-in. -The configuration could also be embedded into a *glossarify-md.conf.json*. But keep in mind that anything under the `unified` key is a [unified configuration][unified-config] whose schema is *not* subject to the [glossarify-md] config schema. +You could also embed the configuration in a *glossarify-md.conf.json*. But keep in mind that anything under the `unified` key is a different schema and *not* subject to the [glossarify-md] config schema. -> **[unified], [remark], uhh..** +> **[remark], [unified], uhh... ?** > > Read more on how these projects relate to glossarify-md in our [Addendum: Conceptual Layers](https://github.com/about-code/glossarify-md/blob/master/doc/conceptual-layers.md) diff --git a/demo/conceptual-layers.md b/demo/conceptual-layers.md index bca498da..9781069c 100644 --- a/demo/conceptual-layers.md +++ b/demo/conceptual-layers.md @@ -8,12 +8,13 @@ Conceptual layers and projects contributing to the layer | 3 | [unified] | umbrella project for *text file processing in general* | | 2 | [remark] | unified *processor* for *markdown text file processing in particular* | | 1 | [micromark] | remarks internal markdown syntax tokenizer | -| 0 | [CommonMark] | Markdown Syntax Specification for your files | +| 0 | [CommonMark] | Informal Markdown Syntax Specification | +[glossarify-md] is built on [unified], an umbrella project for *text file processing in general*. We use [unified] with [remark], which in conceptual terms of [unified] is a *processor* for *Markdown text files in particular*. [remark] itself only supports the [CommonMark] specification via its *internal* [micromark] parser/tokenizer. -[glossarify-md] is built on [unified], an umbrella project for *text file processing in general*. We use [unified] with [remark], which in conceptual terms of [unified] is a *processor* for *Markdown text files in particular*. +That's why you need to install additional [remark plug-ins][remark-plugins] when you need extended Markdown syntax. Those plug-ins then usually install and depend on a [micromark] extension to parse and tokenize that syntax. We omitted for simplicity that [glossarify-md] already installs [remark-gfm] to also support popular [GitHub Flavoured Markdown][GFM] syntax (e.g. tables) and [remark-footnote] (footnotes). -**When installing [remark plug-ins][remark-plugins]** you might need to know the remark version in use: *[glossarify-md] is already on [remark] 13+ with [micromark].* [micromark] is the parser/tokenizer implementation **internal** to [remark] as of version 13. Unless told you by any [remark plug-in][remark-plugins] you won't likely have to install any micromark extensions yourself when using [glossarify-md]. Just stick with [remark plug-ins][remark-plugins] on layers 2. They should declare their [micromark] requirements for themselves. +Unless told you by any [remark plug-in][remark-plugins] you won't likely have to install any micromark extensions yourself when using [glossarify-md]. Just stick with [remark plug-ins][remark-plugins] on layer 2. They should declare their [micromark] requirements for themselves. [glossarify-md]: https://github.com/about-code/glossarify-md @@ -22,3 +23,5 @@ Conceptual layers and projects contributing to the layer [remark-plugins]: https://github.com/remarkjs/awesome-remark [unified]: https://unifiedjs.com [CommonMark]: https://commonmark.org +[GFM]: https://github.github.com/gfm/ +[remark-footnotes]: https://npmjs.com/package/remark-footnotes diff --git a/doc/conceptual-layers.md b/doc/conceptual-layers.md index 48ebbf00..0d4b8c5b 100644 --- a/doc/conceptual-layers.md +++ b/doc/conceptual-layers.md @@ -8,11 +8,13 @@ Conceptual layers and projects contributing to the layer | 3 | [unified] | umbrella project for *text file processing in general* | | 2 | [remark] | [unifiedā†“][1] *processor* for *markdown text file processing in particular* | | 1 | [micromark] | remarks internal markdown syntax tokenizer | -| 0 | [CommonMark] | Markdown Syntax Specification for your files | +| 0 | [CommonMark] | Informal Markdown Syntax Specification | -[glossarify-md] is built on [unified], an umbrella project for *text file processing in general*. We use [unified] with [remark], which in conceptual terms of [unified] is a *processor* for *Markdown text files in particular*. +[glossarify-md] is built on [unified], an umbrella project for *text file processing in general*. We use [unified] with [remark], which in conceptual terms of [unified] is a *processor* for *Markdown text files in particular*. [remark] itself only supports the [CommonMark] specification via its *internal* [micromark] parser/tokenizer. -**When installing [remark plug-ins][remark-plugins]** you might need to know the [remarkā†“][2] version in use: *[glossarify-md] is already on [remark] 13+ with [micromark].* [micromark] is the parser/tokenizer implementation **internal** to [remark] as of version 13. Unless told you by any [remark plug-in][remark-plugins] you won't likely have to install any micromark extensions yourself when using [glossarify-md]. Just stick with [remark plug-ins][remark-plugins] on layers 2. They should declare their [micromark] requirements for themselves. +That's why you need to install additional [remark plug-ins][remark-plugins] when you need extended Markdown syntax. Those plug-ins then usually install and depend on a [micromark] extension to parse and tokenize that syntax. We omitted for simplicity that [glossarify-md] already installs \[remark-gfm] to also support popular [GitHub Flavoured Markdown][GFM] syntax (e.g. tables) and \[remark-footnote] (footnotes). + +Unless told you by any [remark plug-in][remark-plugins] you won't likely have to install any micromark extensions yourself when using [glossarify-md]. Just stick with [remark plug-ins][remark-plugins] on layer 2. They should declare their [micromark] requirements for themselves. [glossarify-md]: https://github.com/about-code/glossarify-md @@ -26,6 +28,8 @@ Conceptual layers and projects contributing to the layer [CommonMark]: https://commonmark.org -[1]: ./glossary.md#unified "unified is an umbrella project around text file processing in general." +[GFM]: https://github.github.com/gfm/ -[2]: ./glossary.md#remark "remark is a parser and compiler project under the unified umbrella for Markdown text files in particular." +[remark-footnotes]: https://npmjs.com/package/remark-footnotes + +[1]: ./glossary.md#unified "unified is an umbrella project around text file processing in general." diff --git a/md/README.md b/md/README.md index b5ba4539..7ec16116 100644 --- a/md/README.md +++ b/md/README.md @@ -656,7 +656,9 @@ key: This is a frontmatter --- ``` -Without special support for it our Markdown parser ([remark]) will recognise the line of trailing dashes as Markdown syntax for a *heading*. To make it aware that they contribute to syntax for a *frontmatter* we need to enhance the parser. **Since v5.0.0** we have opened [glossarify-md] to the [remark plug-in ecosystem][remark-plugins] and its extensive support of additional syntaxes and tools: +Without special support for it our Markdown parser ([remark]) will interpret the line of trailing dashes as Markdown syntax for a *heading*. To make it aware that they contribute to syntax for a *frontmatter* we need to enhance the parser. **Since v5.0.0** we have opened [glossarify-md] to the [remark plug-in ecosystem][remark-plugins] and its extensive support of additional syntaxes and tools: + +> **Note:** glossarify-md must not be held responsible for issues arising due to installing and using additional plug-ins. *Add this to your glossarify-md.conf.json* @@ -687,20 +689,19 @@ and make remark load the plug-in by adding to your *remark.conf.json*: } ``` -> **Note:** glossarify-md must not be held responsible for issues arising due to installing and using additional plug-ins. - `remark.conf.json` follows the [unified configuration][unified-config] schema: - `remark-frontmatter` must be the name of the npm package you installed before. - Any properties of the object are specific to the plug-in. -The configuration could also be embedded into a *glossarify-md.conf.json*. But keep in mind that anything under the `unified` key is a [unified configuration][unified-config] whose schema is *not* subject to the [glossarify-md] config schema. +You could also embed the configuration in a *glossarify-md.conf.json*. But keep in mind that anything under the `unified` key is a different schema and *not* subject to the [glossarify-md] config schema. -> **[unified], [remark], uhh..** +> **[remark], [unified], uhh... ?** > > Read more on how these projects relate to glossarify-md in our [Addendum: Conceptual Layers](https://github.com/about-code/glossarify-md/blob/master/doc/conceptual-layers.md) + ## Node Support Matrix The term *support* refers to *runs on the given platform* and is subject to the terms and conditions in [LICENSE](#license).