fix: --init --new wrongly assumes ./docs/glossary.md exists (#224)

* fix: assumes ./docs/glossary.md to exist * chore: docs
about-code · Nov 17, 2021 · d6bc34d · d6bc34d
1 parent 0cc57bd
commit d6bc34d
Show file tree

Hide file tree

Showing 9 changed files with 243 additions and 181 deletions.
diff --git a/bin/index.js b/bin/index.js
@@ -239,7 +239,7 @@ function writeInitialConf(conf, argv) {
     if (argv.new) {
         const glossaryFile = path.resolve(conf.baseDir, "glossary.md");
         const configFile = path.resolve(conf.baseDir, "../glossarify-md.conf.json");
-        if (fs.pathExists(glossaryFile)) {
+        if (fs.pathExistsSync(glossaryFile)) {
             console.log(`⚠ Warning: ${glossaryFile} already exists. Nothing written.`);
         } else {
             fs.outputFileSync(glossaryFile, "# Glossary", "utf8");

diff --git a/doc/README.md b/doc/README.md
@@ -12,6 +12,8 @@
 
 [doc-pandoc]: ./pandoc.md
 
+[doc-plugins]: ./plugins.md
+
 [doc-glossary]: ./glossary.md
 
 [SKOS]: http://w3.org/skos/
@@ -30,14 +32,19 @@
 
 # [Advanced Topics](#advanced-topics)
 
-Concepts
+[Glossary][doc-glossary] (of glossarify-md)
+
+Markdown Syntax
 
 *   [Markdown Syntax Extensions][doc-syntax-extensions]
+*   [Installing Syntax Plug-ins][doc-plugins]
+
+Exporting and Importing
+
 *   [Vocabulary and Term URIs][doc-vocabulary-uris]
 *   [SKOS Interoperability with JSON-LD][doc-skos-interop]
-*   [Glossary of glossarify-md][doc-glossary]
 
-Using with others
+Further Processing
 
 *   [Using glossarify-md with vuepress][doc-vuepress]
 *   [Using glossarify-md with pandoc][doc-pandoc]

diff --git a/doc/markdown-syntax-extensions.md b/doc/markdown-syntax-extensions.md
@@ -2,6 +2,8 @@
 
 [doc-conceptual-layers]: ./conceptual-layers.md
 
+[doc-plugins]: ./plugins.md
+
 [CommonMark]: https://www.commonmark.org
 
 [GFM]: https://github.github.com/gfm/
@@ -24,8 +26,6 @@
 
 [vuepress]: https://vuepress.vuejs.org
 
-> **ⓘ Since v5.0.0**
-
 [glossarify-md] supports [CommonMark] and [GitHub Flavoured Markdown (GFM)][GFM]. Syntax not covered by these specifications may have no or worse, a wrong representation in the tool's [Abstract Syntax Tree][mdast]. As a consequence it may not make it correctly into output documents. For example *Frontmatter* syntax is a Markdown syntax extension popularized by many static site generators:
 
 *Frontmatter Syntax*
@@ -34,48 +34,6 @@
     key: This is a frontmatter
     ---
 
-Without special support for it [CommonMark] compliant parsers like our [remark] parser will interpret the line of trailing dashes as *heading* markers and the text before them as *heading text*. So to make our parser aware of frontmatter syntax we need to enhance it. **Since v5.0.0** we have opened [glossarify-md] to the [remark plug-in ecosystem][remark-plugins] and its support of additional syntaxes and tools.
-
-## [Installing a Syntax Plug-in](#installing-a-syntax-plug-in)
-
-> **☛ Note:** glossarify-md does not guarantee compatibility with plug-ins and likely won't help with issues arising due to installing and using additional plug-ins.
-
-Next to your `outDir` create a file `remark.conf.json`. Then add to your `glossarify-md.conf.json`:
-
-```json
-{
-  "unified": {
-    "rcPath": "../remark.conf.json"
-  }
-}
-```
-
-`rcPath` is interpreted relative to `outDir`. Then install a [remark🟉][1] plug-in
-
-    npm install remark-frontmatter
-
-and make [remark🟉][1] load the plug-in by adding to your `remark.conf.json`:
-
-```json
-{
-  "plugins": {
-    "remark-frontmatter": {
-      "type": "yaml",
-      "marker": "-"
-    }
-  }
-}
-```
-
-`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.
-
-You could also embed the configuration into a glossarify-md.conf.json by replacing `rcPath` with the `plugins` key. But keep in mind that anything under the `unified` key is a different config schema and *not* subject to the [glossarify-md] config schema.
-
-> **ⓘ [remark], [unified], uhh... ?**
->
-> Read more on how these projects relate to glossarify-md in our addendum [Conceptual Layers][doc-conceptual-layers].
+Without special support for it [CommonMark] compliant parsers like our [remark] parser will interpret the line of trailing dashes as *heading* markers and the text before them as *heading text*. So to make our parser aware of frontmatter syntax we need to enhance it.
 
-[1]: ./glossary.md#remark "remark is a parser and compiler project under the unified umbrella for Markdown text files in particular."
+**Since v5.0.0** we have opened [glossarify-md] to the [remark plug-in ecosystem][remark-plugins] and its support of additional syntaxes and tools. More see [Installing Plug-ins][doc-plugins].
diff --git a/doc/plugins.md b/doc/plugins.md
@@ -0,0 +1,63 @@
+# [Installing Syntax Plug-ins](#installing-syntax-plug-ins)
+
+[doc-conceptual-layers]: ./conceptual-layers.md
+
+[CommonMark]: https://www.commonmark.org
+
+[glossarify-md]: https://github.com/about-code/glossarify-md
+
+[remark]: https://github.com/remarkjs/remark
+
+[remark-frontmatter]: https://npmjs.com/package/remark-frontmatter
+
+[remark-plugin]: https://github.com/remarkjs/awesome-remark
+
+[unified]: https://unifiedjs.com
+
+[unified-config]: https://github.com/unifiedjs/unified-engine/blob/main/doc/configure.md
+
+The following example demonstrates how to install a [remark plug-in][remark-plugin]. The plug-in will extend glossarify-md's markdown parser [remark]  with support for *Frontmatter* syntax.
+
+> **☛ Note:** glossarify-md does not guarantee compatibility with plug-ins and likely won't help with issues arising due to installing and using additional third-party plug-ins.
+
+**1:** Next to your `outDir` create a file `remark.conf.json`. Then add to your `glossarify-md.conf.json`:
+
+```json
+{
+  "unified": {
+    "rcPath": "../remark.conf.json"
+  }
+}
+```
+
+`rcPath` is interpreted relative to `outDir`.
+
+**2:** Then install a [remark plug-in][remark-plugin]
+
+    npm install remark-frontmatter
+
+**3:** Make [remark🟉][1] load the plug-in by adding to your `remark.conf.json`:
+
+```json
+{
+  "plugins": {
+    "remark-frontmatter": {
+      "type": "yaml",
+      "marker": "-"
+    }
+  }
+}
+```
+
+`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.
+
+You could also embed the configuration into a glossarify-md.conf.json by replacing `rcPath` with the `plugins` key. But keep in mind that anything under the `unified` key is a different config schema and *not* subject to the [glossarify-md] config schema.
+
+> **ⓘ [remark], [unified], uhh... ?**
+>
+> Read more on how these projects relate to glossarify-md in [Conceptual Layers][doc-conceptual-layers].
+
+[1]: ./glossary.md#remark "remark is a parser and compiler project under the unified umbrella for Markdown text files in particular."
diff --git a/doc/vuepress.md b/doc/vuepress.md
@@ -2,8 +2,16 @@
 
 Below we assume a *sample* project structure like this:
 
+[doc-syntax-extensions]: ./markdown-syntax-extensions.md
+
 [CommonMark]: https://www.commonmark.org
 
+[github-slugger]: https://npmjs.com/package/github-slugger
+
+[glossarify-md]: https://github.com/about-code/glossarify-md
+
+[vuepress]: https://vuepress.vuejs.org
+
     ${root}
        +- docs/
        |   +- .vuepress/
@@ -39,63 +47,68 @@ Below we assume a *sample* project structure like this:
     "baseDir": "./docs",
     "outDir": "../docs-glossarified",
     "glossaries": [
-        { "file": "./glossary.md", "termHint": "↴"},
+        { "file": "./glossary.md", "termHint": "🟉"},
     ]
 }
 ```
 
-> **Notes**
->
-> ☛ All relative paths inside the config file are being interpreted
-> relativ to `baseDir` except for `$schema` which is relative to the config file.
+> **ⓘ Note:** All relative paths inside the config file are being interpreted relativ to `baseDir` except of `$schema` which is relative to the config file.
 
 ## [Configure vuepress](#configure-vuepress)
 
+[glossarify-md] and [vuepress] need to be aligned in terms of how they create section anchors. More on the *why* see [Appendix][1].
+
+<em>./docs/.vuepress/config.js</em>
+
 ```js
-// .vuepress/config.js
-const glossarify = require("glossarify-md");
+const slugify = {
+  slugify: require("glossarify-md").getSlugger();
+};
 module.exports = {
-    /* ... */
-    markdown: {
-      slugify: glossarify.getSlugger()
-    }
+    markdown: { ...slugify }    // vuepress v1.x
+    // markdown: {               // vuepress v2.x
+    //   toc: { ...slugify },
+    //   anchor: { ...slugify },
+    //   extractHeaders: { ...slugify }
+    // }
 };
 ```
 
-Details on why we have to use a modified [slug🟉][1] algorithm with [vuepress🟉][2] and can be found in [Appendix][3].
-
-> **Warnings**
+> ⚠ **Important:** Vuepress maps headings onto section anchors which become part of a URL fragment like `http://.../#foo-anchor`. By default vuepress creates anchors with lowercase ASCII characters, only. In contrast [github-slugger] will map unicode characters onto their lowercase unicode equivalent, which then affects you our your readers in the following way:
 >
-> ⚠ Changing the slug algorithm might be a breaking change in *published* docs. URLs, especially URL fragments may change. Bookmarks of your readers may become outdated.
+> 1.  Readers who bookmarked a section URL with an ASCII-only `#`-URL fragment will still be able to open the web page they've bookmarked. But as a minor inconvenience their browser may no longer scroll to the bookmarked page section.
 >
-> ⚠ For headings with unicode characters, e.g. `# Äquator` vuepress generates lowercase slugs with ASCII characters, only, which you might referred to by links `[Äquator](#aquator)`. [glossarify-md]'s slugger keeps non-ASCII characters and requires you to refer to the same heading by `[Äquator](#äquator)`, so by a lowercase slug with **ä**.
+> 2.  Writers who linke to a heading with unicode characters (e.g. `# Äquator`[^1]) using a markdown link `[Foo](#aquator)` may need to change the link target to `[Foo](#äquator)`, so need to replace `#a...` with **#ä...**.
+
+[^1]: German term for *Equator*
 
 ## [Configure Build Scripts](#configure-build-scripts)
 
 *package.json*
 
 ```json
 "scripts": {
-  "glossarify": "glossarify-md --config ./glossarify-md.conf.json",
   "start": "vuepress dev docs",
+  "glossarify": "glossarify-md --config ./glossarify-md.conf.json",
   "glossarified": "npm run glossarify && vuepress dev docs-glossarified",
-  "build": "npm run glossarify && vuepress build docs-glossarified",
+  "build": "npm run glossarify && vuepress build docs-glossarified"
 }
 ```
 
 *   `npm start` builds and serves files quickly from `baseDir` with *live-reload*. This is what you probably want while writing even though it doesn't produce glossarified output.
+*   `npm run glossarify` writes glossarified markdown files to `outDir`
 *   `npm run glossarified` builds and serves the glossarified version from `outDir`.
-*   `npm run build` just builds the glossarified version without running a server.
+*   `npm run build` just builds the glossarified [vuepress🟉][2] site without running a server.
 
-More information see [README.md][4].
+More information see [README.md][3].
 
 ## [Markdown Extensions](#markdown-extensions)
 
-[Vuepress🟉][2] has a few [Markdown Extensions][5]. Most of them work out of the box. Though, *Frontmatter* requires a plug-in to work with glossarify-md. Read [Markdown Syntax Extensions][6], for using glossarify-md with Markdown syntax not covered by the [CommonMark] Spec.
+[Vuepress🟉][2] supports some [Markdown Syntax][4] not covered by [CommonMark]. While most of it will work out of the box, *Frontmatter Syntax* requires a plug-in to work with glossarify-md (see [Markdown Syntax Extensions][doc-syntax-extensions]).
 
-| [Vuepress🟉][2] Markdown Extension    | [remark🟉][7] plug-in required with glossarify-md |
+| [Vuepress🟉][2] Markdown Extension    | [remark🟉][5] plug-in required with glossarify-md |
 | ------------------------------------- | ------------------------------------------------- |
-| [Frontmatter][vp-frontmatter]         | [remark-frontmatter][8]                           |
+| [Frontmatter][vp-frontmatter]         | [remark-frontmatter][6]                           |
 | [Custom Containers][vp-cc]            | None                                              |
 | [GitHub Style Tables][vp-gh-tables]   | None                                              |
 | [Table of Contents][vp-toc] `[[toc]]` | None                                              |
@@ -119,46 +132,42 @@ More information see [README.md][4].
 
 ## [Appendix](#appendix)
 
-[glossarify-md] requires a [slug🟉][1] algorithm to create friendly [URL fragments🟉][9] (#...) for section links. When [vuepress🟉][2] translates *glossarified markdown* to HTML it does the same once again for the same purpose. If both tools use different slug algorithms then there's the risk of both generating different fragments which can break links in some situations ([#27][10]). So it's best to configure vuepress to use the same slugger as [glossarify-md].
+[glossarify-md] and [vuepress] both emply a [slug🟉][7] algorithm to create friendly [URL fragments🟉][8] (`#...`) for section links. When [vuepress🟉][2] is fed with *glossarified markdown* sources it will attempt to slug URLs again. If both tools use different slug algorithms then there's a risk of both generating different [URL🟉][9] fragments which can break links in a book (see [#27][10]). To avoid this vuepress needs to be configured to use the same slugger as [glossarify-md].
+
+[glossarify-md] uses [github-slugger] internally. In case you want to get rid of [glossarify-md] you likely not want to have [slugs🟉][7] change again. Then you can use [github-slugger] standalone with [vuepress🟉][2], like so:
 
-[glossarify-md] uses [github-slugger][11] internally. In case you no longer want to use [glossarify-md] you might not want to have [slugs🟉][1] change again. Then you can use the slugger directly with [vuepress🟉][2], too:
+*Using github-slugger without glossarify-md*
 
 ```js
-//.vuepress/config.js
 const GitHubSlugger = require("github-slugger");
-module.exports = {
-  /* ... */
-  markdown: {
-    slugify: (value) => {
+const slugify = {
+  slugify: (value) => {
       const slugifier = new GitHubSlugger();
       return slugifier.slug(value);
-    }
   }
 };
-```
-
-[vuepress]: https://vuepress.vuejs.org
 
-[glossarify-md]: https://github.com/about-code/glossarify-md
+module.exports = {
+  /* see section "Configure vuepress"... */
+};
+```
 
-[1]: ./glossary.md#slug "A slug by our definition is a URL-friendly identifier created from arbitrary text that can be used within URL fragments to address headings / sections on a page."
+[1]: #appendix
 
 [2]: ./glossary.md#vuepress "vuepress is a static website generator translating markdown files into a website powered by vuejs."
 
-[3]: #appendix
+[3]: ../README.md
 
-[4]: ../README.md
+[4]: https://vuepress.vuejs.org/guide/markdown.html
 
-[5]: https://vuepress.vuejs.org/guide/markdown.html
+[5]: ./glossary.md#remark "remark is a parser and compiler project under the unified umbrella for Markdown text files in particular."
 
-[6]: ../README.md#markdown-syntax-extensions
+[6]: http://unifiedjs.com/explore/package/remark-frontmatter/
 
-[7]: ./glossary.md#remark "remark is a parser and compiler project under the unified umbrella for Markdown text files in particular."
+[7]: ./glossary.md#slug "A slug by our definition is a URL-friendly identifier created from arbitrary text that can be used within URL fragments to address headings / sections on a page."
 
-[8]: http://unifiedjs.com/explore/package/remark-frontmatter/
+[8]: ./glossary.md#url-fragment "The fragment is the part follwing the # in a URL."
 
-[9]: ./glossary.md#url-fragment "The fragment is the part follwing the # in a URL."
+[9]: ./glossary.md#uri--url "Uniform Resource Identifier and Uniform Resource Locator describe both the same thing, which is an ID with a syntax scheme://authority.tld/path/#fragment?query like https://my.org/foo/#bar?q=123."
 
 [10]: https://github.com/about-code/glossarify-md/issues/27
-
-[11]: https://npmjs.com/package/github-slugger
diff --git a/md/doc/README.md b/md/doc/README.md
@@ -5,6 +5,7 @@
 [doc-conceptual-layers]: ./conceptual-layers.md
 [doc-lists-on-github]: ./lists-on-github.md
 [doc-pandoc]: ./pandoc.md
+[doc-plugins]: ./plugins.md
 [doc-glossary]: ./glossary.md
 [SKOS]: http://w3.org/skos/
 [LD]: https://www.w3.org/standards/semanticweb/ontology
@@ -16,13 +17,18 @@
 
 # Advanced Topics
 
-Concepts
-- [Markdown Syntax Extensions][doc-syntax-extensions]
-- [Vocabulary and Term URIs][doc-vocabulary-uris]
-- [SKOS Interoperability with JSON-LD][doc-skos-interop]
-- [Glossary of glossarify-md][doc-glossary]
+ [Glossary][doc-glossary] (of glossarify-md)
 
-Using with others
+Markdown Syntax
+  - [Markdown Syntax Extensions][doc-syntax-extensions]
+  - [Installing Syntax Plug-ins][doc-plugins]
+
+Exporting and Importing
+  - [Vocabulary and Term URIs][doc-vocabulary-uris]
+  - [SKOS Interoperability with JSON-LD][doc-skos-interop]
+
+
+Further Processing
 - [Using glossarify-md with vuepress][doc-vuepress]
 - [Using glossarify-md with pandoc][doc-pandoc]