chore(test): New test cases. (#182)

* Fix inconcistencies around linking.byReferenceDefinition
* Update docs
* Wording
* test: New test case.
* test: New baseline.
* Code style

README.md

@@ -1006,9 +1006,9 @@ Whether to convert inline-links to [link reference definitions] (size-efficient)
 - **Default:** `true`
 - **Since:** v6.0.0
 
-Whether to linkify headings. Note that some Markdown-to-HTML renderers need headings to be linkified in order to be rendered URL-addressable and navigable. Others like [pandoc] don't care about linkification but presence of additional syntax.
+Whether to linkify headings. Note that some Markdown-to-HTML renderers need headings to be linkified in order to be rendered URL-addressable and navigable. Others like [pandoc] don't need linkified headings but special syntax.
 
-See also
+See also:
 
 - [`linking.headingIdPandoc`](#linkingheadingidpandoc)
 
@@ -1028,7 +1028,7 @@ Use this option to select markdown heading depths which should be considered ter
 - **Default:** `"github"`
 - **Since:** v6.0.0
 
-Algorithm to use for generating heading identifiers (slugs). `"github"` will only guarantee *unique-per file* IDs. The MD5 and SHA256 options will make [glossarify-md] calculate a hash over file path and heading phrase. So they are able to guarantee *unique-in-fileset* IDs given that a particular heading phrase occurs *once only* within a file. For brevity the `*-7` options truncate hashes to a maximum length of 7. They will still be unlikely to collide in a typical project. You'll need *unique-in-fileset* IDs if plan on concatenating output files, e.g. with [pandoc]. Otherwise links in the final result aren't guaranteed to reference the correct target anymore.
+Algorithm to use for generating heading identifiers (slugs). `"github"` will only guarantee *unique-per file* IDs. The MD5 and SHA256 options will make [glossarify-md] calculate a hash over file path and heading phrase. So they are able to guarantee *unique-in-fileset* IDs given that a particular heading phrase occurs *once only* within a file. For brevity the `*-7` options truncate hashes to a maximum length of 7. They will still be unlikely to collide in a typical project. You'll need *unique-in-fileset* IDs if you plan on concatenating output files, e.g. with [pandoc]. Otherwise links in the final result aren't guaranteed to reference the correct target anymore.
 
 #### `linking.headingIdPandoc`
 
@@ -1090,6 +1090,8 @@ Allows to tweak which components of a file path should make it into auto-generat
 - `["path", "file"]` => `./glossary/default#term`
 - `["file"]` => `default#term`
 
+Use `linking.paths: "none"` if you would like to have a fragment (`#`) but no path components.
+
 #### `outDir`
 
 - **Range:** `string`

lib/identifier.js

@@ -10,7 +10,7 @@ import { getVFilePath } from "./path/tools.js";
  *
  * @param {{ algorithm: string }} args Algorithm
  */
-export function identifier (args) {
+export function identifier(args) {
     const slugs = new BananaSlug();
     const algorithm = /^([a-zA-Z0-9]+)-?([0-9]{0,4})$/.exec(args.algorithm);
     return (tree, vFile) => {

md/README.md

@@ -960,9 +960,9 @@ Whether to convert inline-links to [link reference definitions] (size-efficient)
 - **Default:** `true`
 - **Since:** v6.0.0
 
-Whether to linkify headings. Note that some Markdown-to-HTML renderers need headings to be linkified in order to be rendered URL-addressable and navigable. Others like [pandoc] don't care about linkification but presence of additional syntax.
+Whether to linkify headings. Note that some Markdown-to-HTML renderers need headings to be linkified in order to be rendered URL-addressable and navigable. Others like [pandoc] don't need linkified headings but special syntax.
 
-See also
+See also:
 
 - [`linking.headingIdPandoc`](#linkingheadingidpandoc)
 
@@ -983,7 +983,7 @@ Use this option to select markdown heading depths which should be considered ter
 - **Default:** `"github"`
 - **Since:** v6.0.0
 
-Algorithm to use for generating heading identifiers (slugs). `"github"` will only guarantee *unique-per file* IDs. The MD5 and SHA256 options will make [glossarify-md] calculate a hash over file path and heading phrase. So they are able to guarantee *unique-in-fileset* IDs given that a particular heading phrase occurs *once only* within a file. For brevity the `*-7` options truncate hashes to a maximum length of 7. They will still be unlikely to collide in a typical project. You'll need *unique-in-fileset* IDs if plan on concatenating output files, e.g. with [pandoc]. Otherwise links in the final result aren't guaranteed to reference the correct target anymore.
+Algorithm to use for generating heading identifiers (slugs). `"github"` will only guarantee *unique-per file* IDs. The MD5 and SHA256 options will make [glossarify-md] calculate a hash over file path and heading phrase. So they are able to guarantee *unique-in-fileset* IDs given that a particular heading phrase occurs *once only* within a file. For brevity the `*-7` options truncate hashes to a maximum length of 7. They will still be unlikely to collide in a typical project. You'll need *unique-in-fileset* IDs if you plan on concatenating output files, e.g. with [pandoc]. Otherwise links in the final result aren't guaranteed to reference the correct target anymore.
 
 #### `linking.headingIdPandoc`
 
@@ -1047,6 +1047,7 @@ Allows to tweak which components of a file path should make it into auto-generat
 - `["path", "file"]` => `./glossary/default#term`
 - `["file"]` => `default#term`
 
+Use `linking.paths: "none"` if you would like to have a fragment (`#`) but no path components.
 
 #### `outDir`
 

test/input/config-glossaries/file-glob-and-glossaries-disjunct/documents/document-a.md

@@ -0,0 +1,21 @@
+# Document A
+
+- GIVEN a configuration
+
+  ~~~json
+  "glossaries": [
+    { "file": "./documents/**/document-*.md" },
+    { "file": "./glossaries/glossary-a.md", "termHint": "🄰 ${term}" },
+    { "file": "./glossaries/glossary-b.md", "termHint": "🄱 ${term}" }
+  ]
+  ~~~
+
+- AND a set x of glossaries found by glob pattern
+- AND a set y of glossaries listed explicitly
+- AND both sets x and y being disjunct
+- THEN term *Alpha* from Glossary A MUST be linked
+- AND term *Heading B* from Document B MUST be linked
+
+## Heading A
+
+Heading of Document A.

test/input/config-glossaries/file-glob-and-glossaries-disjunct/documents/document-b.md

@@ -0,0 +1,22 @@
+# Document B
+
+- GIVEN a configuration
+
+  ~~~json
+  "glossaries": [
+    { "file": "./documents/**/document-*.md" },
+    { "file": "./glossaries/glossary-a.md", "termHint": "🄰 ${term}" },
+    { "file": "./glossaries/glossary-b.md", "termHint": "🄱 ${term}" }
+  ]
+  ~~~
+
+- AND a set x of glossaries found by glob pattern
+- AND a set y of glossaries listed explicitly
+- AND both sets x and y being disjunct
+- THEN term *Beta* from Glossary B MUST be linked
+- AND term *Heading A* from Document A MUST be linked
+
+
+## Heading B
+
+Heading of Document B.

test/input/config-glossaries/file-glob-and-glossaries-disjunct/glossaries/glossary-a.md

@@ -0,0 +1,5 @@
+# Glossary A
+
+## Alpha
+
+Term in Glossary A.

test/input/config-glossaries/file-glob-and-glossaries-disjunct/glossaries/glossary-b.md

@@ -0,0 +1,5 @@
+# Glossary B
+
+## Beta
+
+Term in Glossary B.

test/input/config-glossaries/file-glob-and-glossaries-disjunct/glossarify-md.conf.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "../../../../conf/v5/schema.json",
+  "baseDir": ".",
+  "outDir": "../../../output-actual/config-glossaries/file-glob-and-glossaries-disjunct",
+  "glossaries": [
+    { "file": "./documents/**/document-*.md" },
+    { "file": "./glossaries/glossary-a.md", "termHint": "🄰 ${term}" },
+    { "file": "./glossaries/glossary-b.md", "termHint": "🄱 ${term}" }
+  ]
+}

test/input/config-linking/paths-relative-pathComponents/none/glossarify-md.conf.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "../../../../../conf/v5/schema.json",
+  "baseDir": ".",
+  "outDir": "../../../../output-actual/config-linking/paths-relative-pathComponents/none",
+  "linking": {
+    "paths": "relative",
+    "pathComponents": []
+  },
+  "generateFiles": {
+    "listOfTables": {
+      "file": "./tables.md"
+    },
+    "listOfFigures": {
+      "file": "./figures.md"
+    },
+    "listOf": [{
+      "class": "foo",
+      "file": "./foo.md"
+    }]
+  },
+  "glossaries": [{ "file": "./glossary.md" } ]
+}

test/input/config-linking/paths-relative-pathComponents/none/glossary.md

@@ -0,0 +1,5 @@
+# Glossary
+
+## Term
+
+Term definition.

test/input/config-linking/paths-relative-pathComponents/none/sub-1/document.md

@@ -0,0 +1,64 @@
+# Document
+
+GIVEN a configuration
+
+~~~json
+{
+  "linking": {
+    "paths": "relative",
+    "pathComponents": []
+  },
+  "generateFiles": {
+    "listOfTables": {
+      "file": "./tables.md"
+    },
+    "listOfFigures": {
+      "file": "./figures.md"
+    },
+    "listOf": [{
+      "class": "foo",
+      "file": "./foo.md"
+    }]
+  },
+}
+~~~
+
+## Term Links
+
+...WITH this document mentioning glossary term *Term*
+THEN the term must be linked
+AND the link url MUST be `../glossary.md#Term`
+
+## List Of Tables
+
+...WITH a configuration `listOfTable`
+AND and a table
+
+*A table:*
+
+| Head 1 | Head 2 |
+| ------ | ------ |
+| Item 1 | Item 2 |
+
+THEN a file `./tables.md` MUST be generated
+AND there MUST be a list item with caption *A table:*
+AND the list item must be linked
+AND the link MUST be `./sub-1/document.md#a-table`.
+
+## List Of Figures
+
+...WITH a configuration `listOfFigure`
+AND and a figure ![My Figure](./not-found.png)
+THEN a file `./figures.md` MUST be generated
+AND there MUST be a list item with caption *My Figure*
+AND the list item must be linked
+AND the link MUST be `./sub-1/document.md#my-figure`.
+
+## List Of Foo
+
+...WITH a configuration `listOfFigure`
+AND and a <span id="foo-bar">Foo</span>
+THEN a file `./foo.md` MUST be generated
+AND there MUST be a list item with caption *Foo*
+AND the list item must be linked
+AND the link MUST be `./sub-1/document.md#foo-bar`.

test/output-expected/config-glossaries/file-glob-and-glossaries-disjunct/documents/document-a.md

@@ -0,0 +1,29 @@
+# [Document A](#document-a)
+
+*   GIVEN a configuration
+
+    ```json
+    "glossaries": [
+      { "file": "./documents/**/document-*.md" },
+      { "file": "./glossaries/glossary-a.md", "termHint": "🄰 ${term}" },
+      { "file": "./glossaries/glossary-b.md", "termHint": "🄱 ${term}" }
+    ]
+    ```
+
+*   AND a set x of glossaries found by glob pattern
+
+*   AND a set y of glossaries listed explicitly
+
+*   AND both sets x and y being disjunct
+
+*   THEN term *[🄰 Alpha][1]* from Glossary A MUST be linked
+
+*   AND term *[Heading B][2]* from Document B MUST be linked
+
+## [Heading A](#heading-a)
+
+Heading of Document A.
+
+[1]: ../glossaries/glossary-a.md#alpha "Term in Glossary A."
+
+[2]: ./document-b.md#heading-b "Heading of Document B."

test/output-expected/config-glossaries/file-glob-and-glossaries-disjunct/documents/document-b.md

@@ -0,0 +1,29 @@
+# [Document B](#document-b)
+
+*   GIVEN a configuration
+
+    ```json
+    "glossaries": [
+      { "file": "./documents/**/document-*.md" },
+      { "file": "./glossaries/glossary-a.md", "termHint": "🄰 ${term}" },
+      { "file": "./glossaries/glossary-b.md", "termHint": "🄱 ${term}" }
+    ]
+    ```
+
+*   AND a set x of glossaries found by glob pattern
+
+*   AND a set y of glossaries listed explicitly
+
+*   AND both sets x and y being disjunct
+
+*   THEN term *[🄱 Beta][1]* from Glossary B MUST be linked
+
+*   AND term *[Heading A][2]* from Document A MUST be linked
+
+## [Heading B](#heading-b)
+
+Heading of Document B.
+
+[1]: ../glossaries/glossary-b.md#beta "Term in Glossary B."
+
+[2]: ./document-a.md#heading-a "Heading of Document A."

test/output-expected/config-glossaries/file-glob-and-glossaries-disjunct/glossaries/glossary-a.md

@@ -0,0 +1,5 @@
+# [Glossary A](#glossary-a)
+
+## [Alpha](#alpha)
+
+Term in Glossary A.

test/output-expected/config-glossaries/file-glob-and-glossaries-disjunct/glossaries/glossary-b.md

@@ -0,0 +1,5 @@
+# [Glossary B](#glossary-b)
+
+## [Beta](#beta)
+
+Term in Glossary B.

test/output-expected/config-glossaries/file-glob-and-glossaries-disjunct/glossarify-md.conf.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "../../../../conf/v5/schema.json",
+  "baseDir": ".",
+  "outDir": "../../../output-actual/config-glossaries/file-glob-and-glossaries-disjunct",
+  "glossaries": [
+    { "file": "./documents/**/document-*.md" },
+    { "file": "./glossaries/glossary-a.md", "termHint": "🄰 ${term}" },
+    { "file": "./glossaries/glossary-b.md", "termHint": "🄱 ${term}" }
+  ]
+}

test/output-expected/config-linking/paths-relative-pathComponents/none/figures.md

@@ -0,0 +1,9 @@
+# [Figures](#figures)
+
+
+### [List Of Figures](#list-of-figures)  
+
+1.  [My Figure][1]  
+
+
+[1]: ./sub-1/document.md#my-figure "My Figure"

test/output-expected/config-linking/paths-relative-pathComponents/none/foo.md

@@ -0,0 +1,9 @@
+# [Foo](#foo)
+
+
+### [List Of Foo](#list-of-foo)  
+
+1.  [Foo][1]  
+
+
+[1]: ./sub-1/document.md#foo-bar "Foo"

test/output-expected/config-linking/paths-relative-pathComponents/none/glossarify-md.conf.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "../../../../../conf/v5/schema.json",
+  "baseDir": ".",
+  "outDir": "../../../../output-actual/config-linking/paths-relative-pathComponents/none",
+  "linking": {
+    "paths": "relative",
+    "pathComponents": []
+  },
+  "generateFiles": {
+    "listOfTables": {
+      "file": "./tables.md"
+    },
+    "listOfFigures": {
+      "file": "./figures.md"
+    },
+    "listOf": [{
+      "class": "foo",
+      "file": "./foo.md"
+    }]
+  },
+  "glossaries": [{ "file": "./glossary.md" } ]
+}

test/output-expected/config-linking/paths-relative-pathComponents/none/glossary.md

@@ -0,0 +1,7 @@
+# [Glossary](#glossary)
+
+## [Term](#term)
+
+[Term][1] definition.
+
+[1]: #term "Term definition."