feat: New option linking.pathComponents (#173)

* feat: Path components
* test: New test cases.
* test: New baseline.
* doc: Update config schema docs

conf/v5/doc/schema-defs-linking-properties-pathcomponents-items.md

@@ -0,0 +1,9 @@
+## items Constraints
+
+**enum**: the value of this property must be equal to one of the following values:
+
+| Value    | Explanation |
+| :------- | :---------- |
+| `"path"` |             |
+| `"file"` |             |
+| `"ext"`  |             |

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

@@ -0,0 +1,3 @@
+## pathComponents Constraints
+
+**maximum number of items**: the maximum number of items for this array is: `3`

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

@@ -18,7 +18,7 @@ The base url to use when creating absolute links to glossary.
 
 ## paths
 
-Control how paths to linked documents will be constructed. Choosing "absolute" requires a "baseUrl" as well.
+Control how paths to linked documents will be constructed. When choosing "absolute" you may set a "baseUrl" as well. Without a base URL absolute file system paths will be generated.
 
 `paths`
 
@@ -36,6 +36,20 @@ Control how paths to linked documents will be constructed. Choosing "absolute" r
 | `"absolute"` |             |
 | `"none"`     |             |
 
+## 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.
+
+`pathComponents`
+
+*   is optional
+
+*   Type: `string[]`
+
+### pathComponents Constraints
+
+**maximum number of items**: the maximum number of items for this array is: `3`
+
 ## mentions
 
 Control the link density and whether every occurrence of a term in your documents should be linked with its glossary definition or only the first occurrence within a particular range.

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

@@ -6,6 +6,11 @@ The default value is:
 {
   "baseUrl": "",
   "paths": "relative",
+  "pathComponents": [
+    "path",
+    "file",
+    "ext"
+  ],
   "mentions": "all",
   "headingDepths": [
     2,
@@ -42,7 +47,7 @@ The base url to use when creating absolute links to glossary.
 
 ## paths
 
-Control how paths to linked documents will be constructed. Choosing "absolute" requires a "baseUrl" as well.
+Control how paths to linked documents will be constructed. When choosing "absolute" you may set a "baseUrl" as well. Without a base URL absolute file system paths will be generated.
 
 `paths`
 
@@ -60,6 +65,20 @@ Control how paths to linked documents will be constructed. Choosing "absolute" r
 | `"absolute"` |             |
 | `"none"`     |             |
 
+## 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.
+
+`pathComponents`
+
+*   is optional
+
+*   Type: `string[]`
+
+### pathComponents Constraints
+
+**maximum number of items**: the maximum number of items for this array is: `3`
+
 ## mentions
 
 Control the link density and whether every occurrence of a term in your documents should be linked with its glossary definition or only the first occurrence within a particular range.

conf/v5/doc/schema.md

@@ -208,6 +208,11 @@ The default value is:
 {
   "baseUrl": "",
   "paths": "relative",
+  "pathComponents": [
+    "path",
+    "file",
+    "ext"
+  ],
   "mentions": "all",
   "headingDepths": [
     2,
@@ -702,7 +707,7 @@ The base url to use when creating absolute links to glossary.
 
 ### paths
 
-Control how paths to linked documents will be constructed. Choosing "absolute" requires a "baseUrl" as well.
+Control how paths to linked documents will be constructed. When choosing "absolute" you may set a "baseUrl" as well. Without a base URL absolute file system paths will be generated.
 
 `paths`
 
@@ -720,6 +725,20 @@ Control how paths to linked documents will be constructed. Choosing "absolute" r
 | `"absolute"` |             |
 | `"none"`     |             |
 
+### 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.
+
+`pathComponents`
+
+*   is optional
+
+*   Type: `string[]`
+
+#### pathComponents Constraints
+
+**maximum number of items**: the maximum number of items for this array is: `3`
+
 ### mentions
 
 Control the link density and whether every occurrence of a term in your documents should be linked with its glossary definition or only the first occurrence within a particular range.

conf/v5/schema.json

@@ -82,6 +82,7 @@
             ,"default": {
                 "baseUrl": ""
                 ,"paths": "relative"
+                ,"pathComponents": ["path", "file", "ext"]
                 ,"mentions": "all"
                 ,"headingDepths": [2,3,4,5,6]
                 ,"headingIdAlgorithm": "github"
@@ -281,10 +282,19 @@
                     ,"format": "url"
                 }
                 ,"paths": {
-                    "description": "Control how paths to linked documents will be constructed. Choosing \"absolute\" requires a \"baseUrl\" as well."
+                    "description": "Control how paths to linked documents will be constructed. When choosing \"absolute\" you may set a \"baseUrl\" as well. Without a base URL absolute file system paths will be generated."
                     ,"type": "string"
                     ,"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."
+                    ,"type": "array"
+                    ,"maxItems": 3
+                    ,"items": {
+                        "type": "string",
+                        "enum": ["path", "file", "ext"]
+                    }
+                }
                 ,"mentions": {
                     "description": "Control the link density and whether every occurrence of a term in your documents should be linked with its glossary definition or only the first occurrence within a particular range."
                     ,"type": "string"

lib/path/tools.js

@@ -1,6 +1,7 @@
-import path from "path";
-import { cwd } from "process";
-import url from "url";
+import path from "node:path";
+import { cwd } from "node:process";
+import url from "node:url";
+import { VFile } from "vfile";
 
 const CWD = cwd();
 const forwSlashRegex = new RegExp("\\" + path.sep, "g");
@@ -119,39 +120,43 @@ export function toReproducablePath(fullPath, redactString) {
  */
 export function getFileLinkUrl(context, pathFrom, pathTo, anchor) {
     const { outDir, linking } = context.conf;
-    const { baseUrl, paths } = linking;
-    let targetUrl = "";
-    if (! anchor) {
-        anchor = "";
-    }
-    if (anchor && anchor[0] !== "#") {
-        anchor = `#${anchor}`;
+    const { baseUrl, paths, pathComponents } = linking;
+
+    let targetUrl = {
+        base: ""
+        ,path: ""
+        ,anchor: ""
+    };
+    if (anchor) {
+        targetUrl.anchor = anchor[0] === "#" ? anchor : `#${anchor}`;
     }
     if (paths === "relative") {
-        targetUrl = toForwardSlash(
+        const p = toForwardSlash(
             relativeFromTo(
                 path.resolve(outDir, pathFrom || "."),
                 path.resolve(outDir, pathTo)
             )
         );
-        if (targetUrl === "./") {
-            // link within the same file
-            targetUrl = anchor;
-        } else {
-            targetUrl += anchor;
-        }
+        if (p !== "./") {
+            targetUrl.path = p;
+        } // else: inner link within the same file
     } else if (paths === "absolute") {
         if (baseUrl) {
-            targetUrl = toForwardSlash(path.resolve(outDir, pathTo))
-                .replace(outDir, baseUrl)
-                .replace(/^(.*)(\/|\\)$/, "$1")
-                + anchor;
+            targetUrl.base = baseUrl.replace(/^(.*)(\/|\\)$/, "$1");
+            targetUrl.path = toForwardSlash(path.resolve(outDir, pathTo))
+                .replace(outDir, "");
         } else {
-            targetUrl = toForwardSlash(path.resolve(outDir, pathTo))
-                + anchor;
+            targetUrl.path = toForwardSlash(path.resolve(outDir, pathTo));
         }
-    } else {
-        targetUrl = anchor;
     }
-    return url.parse(targetUrl).format();
+    if (pathComponents && targetUrl.path) {
+        const vFile = new VFile({path: targetUrl.path});
+        const pathTemplate = pathComponents.join(",");
+        const path_ = /path/.test(pathTemplate) ? (vFile.dirname + "/").replace("//", "/") : "";
+        const file  = /file/.test(pathTemplate) ? vFile.stem : "";
+        const ext   = /ext/.test(pathTemplate) ? vFile.extname : "";
+        targetUrl.path = `${path_}${file}${ext}`;
+    }
+    const result = `${targetUrl.base}${targetUrl.path}${targetUrl.anchor}`;
+    return url.parse(result).format();
 }

test/input/config-linking/paths-absolute-pathComponents/path-file-ext/glossarify-md.conf.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "../../../../../conf/v5/schema.json",
+  "baseDir": ".",
+  "outDir": "../../../../output-actual/config-linking/paths-absolute-pathComponents/path-file-ext",
+  "linking": {
+    "baseUrl": "http://localhost/",
+    "paths": "absolute",
+    "pathComponents": ["path", "file", "ext"]
+  },
+  "generateFiles": {
+    "listOfTables": {
+      "file": "./tables.md"
+    },
+    "listOfFigures": {
+      "file": "./figures.md"
+    },
+    "listOf": [{
+      "class": "foo",
+      "file": "./foo.md"
+    }]
+  },
+  "glossaries": [{ "file": "./glossary.md" } ]
+}

test/input/config-linking/paths-absolute-pathComponents/path-file-ext/glossary.md

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

test/input/config-linking/paths-absolute-pathComponents/path-file-ext/sub-1/document.md

@@ -0,0 +1,67 @@
+# Document
+
+GIVEN a configuration
+
+~~~json
+{
+  "linking": {
+    "baseUrl": "http://localhost/",
+    "paths": "absolute",
+    "pathComponents": ["path", "file", "ext"]
+  },
+  "generateFiles": {
+    "listOfTables": {
+      "file": "./tables.md"
+    },
+    "listOfFigures": {
+      "file": "./figures.md"
+    },
+    "listOf": [{
+      "class": "foo",
+      "file": "./foo.md"
+    }]
+  },
+}
+~~~
+
+WITH `baseUrl` being terminated by `/`...
+
+## Term Links
+
+...WITH this document mentioning glossary term *Term*
+THEN the term must be linked
+AND the link url MUST be `http://localhost/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 `http://localhost/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 `http://localhost/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 `http://localhost/sub-1/document.md#foo-bar`.

test/input/config-linking/paths-absolute-pathComponents/path-file/glossarify-md.conf.json

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

test/input/config-linking/paths-absolute-pathComponents/path-file/glossary.md

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