QA

README.md

@@ -566,7 +566,7 @@ The link label for list items will be inferred in this order (first-match):
 > **Since v3.3.0**
 
 So far we used [`listOf`](#lists) to generate a list from *HTML elements* in Markdown. Writing HTML can be annoying, particularly if there is handier Markdown syntax for the elements to be listed. This is where
-`listOfFigures` and [`listOfTables`](#list-of-tables) fits in. It is a shortcut which makes [glossarify-md] generate the HTML anchor itself from Markdown's image syntax:
+`listOfFigures` and [`listOfTables`](#list-of-tables) fit in. It is a shortcut which makes [glossarify-md] generate the HTML anchor itself from Markdown's image syntax:
 
 ```md
 ![List item Label](./figure.png)
@@ -742,7 +742,7 @@ If the regular expression (RegExp) matches text in a paragraph, then *the paragr
 
 > **Which syntax to include in the RegExp**:
 >
-> You may notice that the RegExp above doesn't assume *Task* to be written between `**` star markers. The expression won't be applied directly to the Markdown input *you* wrote but to plain text cleaned from any *recognised* syntax elements of [CommonMark] or [GFM]. If the phrase had contained [unsupported Markdown Syntax][syntax-extensions] then the RegExp had to take care for it to correctly match (more on  see next).
+> You may notice that the RegExp above doesn't assume *Task* to be written between `**` star markers. The expression won't be applied directly to the Markdown input *you* wrote but to plain text cleaned from any *recognised* syntax elements of [CommonMark] or [GFM]. If the phrase had contained [unsupported Markdown Syntax][syntax-extensions] then the RegExp had to take care for it to correctly match (more on syntax extensions below).
 
 ## Markdown Syntax Extensions
 
@@ -965,7 +965,7 @@ Locale options to control [sorting](#sorting-your-glossaries). See [`Intl.Collat
 - **Range:** `string[]`
 
 Paths or Glob-Patterns for Markdown files to copy to `outDir` but keep there as they are without
-glossarifying and linking. Non-markdown files won't be processed anyways, so need to add those.
+glossarifying and linking. Non-markdown files won't be processed anyways, so no need to add those.
 
 #### `linking`
 
@@ -974,7 +974,7 @@ glossarifying and linking. Non-markdown files won't be processed anyways, so nee
 ```
 {
   baseUrl: string,
-  byReference: boolean,
+  byReferenceDefinition: boolean,
   paths: "relative" | "absolute",
   pathComponents: ["path", "file", "ext"],
   mentions: "all" | "first-in-paragraph",
@@ -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`

conf/v5/doc/schema-defs-linking.md

@@ -38,7 +38,7 @@ Control how paths to linked documents will be constructed. When choosing "absolu
 
 ## pathComponents
 
-With path templates and template variables {path}, {file}, {ext} you are able to adjust which path components details (see also "paths" option). Note that path templates must not contain ".." to construct relative-upward paths.
+Adjust which path components should make it into auto-generated links. glossarify-md won't rewrite your own links.
 
 `pathComponents`
 

conf/v5/doc/schema-properties-linking.md

@@ -67,7 +67,7 @@ Control how paths to linked documents will be constructed. When choosing "absolu
 
 ## pathComponents
 
-With path templates and template variables {path}, {file}, {ext} you are able to adjust which path components details (see also "paths" option). Note that path templates must not contain ".." to construct relative-upward paths.
+Adjust which path components should make it into auto-generated links. glossarify-md won't rewrite your own links.
 
 `pathComponents`
 

conf/v5/doc/schema.md

@@ -727,7 +727,7 @@ Control how paths to linked documents will be constructed. When choosing "absolu
 
 ### pathComponents
 
-With path templates and template variables {path}, {file}, {ext} you are able to adjust which path components details (see also "paths" option). Note that path templates must not contain ".." to construct relative-upward paths.
+Adjust which path components should make it into auto-generated links. glossarify-md won't rewrite your own links.
 
 `pathComponents`
 

conf/v5/schema.json

@@ -287,7 +287,7 @@
                     ,"enum": ["relative", "absolute", "none"]
                 }
                 ,"pathComponents": {
-                    "description": "With path templates and template variables {path}, {file}, {ext} you are able to adjust which path components details (see also \"paths\" option). Note that path templates must not contain \"..\" to construct relative-upward paths."
+                    "description": "Adjust which path components should make it into auto-generated links. glossarify-md won't rewrite your own links."
                     ,"type": "array"
                     ,"maxItems": 3
                     ,"items": {

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

@@ -521,7 +521,7 @@ The link label for list items will be inferred in this order (first-match):
 > **Since v3.3.0**
 
 So far we used [`listOf`](#lists) to generate a list from *HTML elements* in Markdown. Writing HTML can be annoying, particularly if there is handier Markdown syntax for the elements to be listed. This is where
-`listOfFigures` and [`listOfTables`](#list-of-tables) fits in. It is a shortcut which makes [glossarify-md] generate the HTML anchor itself from Markdown's image syntax:
+`listOfFigures` and [`listOfTables`](#list-of-tables) fit in. It is a shortcut which makes [glossarify-md] generate the HTML anchor itself from Markdown's image syntax:
 
 ```md
 ![List item Label](./figure.png)
@@ -697,7 +697,7 @@ If the regular expression (RegExp) matches text in a paragraph, then *the paragr
 
 > **Which syntax to include in the RegExp**:
 >
-> You may notice that the RegExp above doesn't assume *Task* to be written between `**` star markers. The expression won't be applied directly to the Markdown input *you* wrote but to plain text cleaned from any *recognised* syntax elements of [CommonMark] or [GFM]. If the phrase had contained [unsupported Markdown Syntax][syntax-extensions] then the RegExp had to take care for it to correctly match (more on  see next).
+> You may notice that the RegExp above doesn't assume *Task* to be written between `**` star markers. The expression won't be applied directly to the Markdown input *you* wrote but to plain text cleaned from any *recognised* syntax elements of [CommonMark] or [GFM]. If the phrase had contained [unsupported Markdown Syntax][syntax-extensions] then the RegExp had to take care for it to correctly match (more on syntax extensions below).
 
 ## Markdown Syntax Extensions
 
@@ -919,7 +919,7 @@ Locale options to control [sorting](#sorting-your-glossaries). See [`Intl.Collat
 - **Range:** `string[]`
 
 Paths or Glob-Patterns for Markdown files to copy to `outDir` but keep there as they are without
-glossarifying and linking. Non-markdown files won't be processed anyways, so need to add those.
+glossarifying and linking. Non-markdown files won't be processed anyways, so no need to add those.
 
 #### `linking`
 
@@ -928,7 +928,7 @@ glossarifying and linking. Non-markdown files won't be processed anyways, so nee
 ~~~
 {
   baseUrl: string,
-  byReference: boolean,
+  byReferenceDefinition: boolean,
   paths: "relative" | "absolute",
   pathComponents: ["path", "file", "ext"],
   mentions: "all" | "first-in-paragraph",
@@ -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/byReferenceDefinition/false/document.md

@@ -3,7 +3,7 @@
 ## Section
 
 GIVEN a document *Document* mentioning glossary term *Term*
-AND a configuration `linking.byReference: false`
+AND a configuration `linking.byReferenceDefinition: false`
 THEN links MUST be placed inline similar to
 
 ~~~md

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."