Bugfix/spaces in headings (#5)

Resolve issue with replacements in title sequences mentioned in issue #6.

* Add test + naive fix for title spacing issue
* Update readme to reflect the current version
* Add option to disable header word replacement

Author: stijn-dejongh

README.md

@@ -2,7 +2,7 @@
 
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=stijn-dejongh_docsify-glossary&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=stijn-dejongh_docsify-glossary)
 
-Simple Glossary for Docsify that replaces occurrences of the terms with links to the glossary.
+Simple Glossary for Docsify that replaces occurrences of words in text with links to the glossary definitions.
 Forked from [TheGreenToaster/docsify-glossary](https://github.com/TheGreenToaster/docsify-glossary) as the original
 project was unmaintained for over 3 years, to address a couple of usability issues with the original script.
 
@@ -19,20 +19,32 @@ An example usage can be found here [./example](./example), it is deployed automa
 1. Create a `_glossary.md` file in the root directory
 2. Populate the `_glossary.md` file with terms.
 
-## Usage
+## Plugim Usage
 
 * Terms must be predicated with a consistent markdown heading to get recognized by the glossary (see configuration)
-* Terms in the documentation must be surrounded by space to get replaced by the regular expression
 * Terms are replaced with links in the order that they appear in the glossary file.
+  * This is especially relevant for nested terminology ( e.g. _API_ and _API Usage_)
 
-## Example
+## Running the code
 
-1. Run `npm run-script build`
-2. Run `docsify serve example`
+In order to run the code, you will need a node set-up on your local machine.
+We recommend using [Node Version Manager](https://npm.github.io/installation-setup-docs/installing/using-a-node-version-manager.html) to make this easier.
+
+### Building the code
+
+1. Globally install [docsify](https://docsify.js.org/#/quickstart): `npm i docsify-cli -g` 
+2. From the project root directory, run: `npm install`
+3. To build the code, run: `npm run ci`
+4. THis will compile, test, and package the plugin
+
+### View the example website
+
+Once the code has been built, you can launch the example website illustrating the use of the glossary.
+In order to do so: 
 3. Go to [http://localhost:3000/]()
 
 ## Changelog
-
+Simple Glossary for Docsify
 An overview of all the changes made to this codebase can be found in the [CHANGELOG](./CHANGELOG.md) file included in this repository.
 
 ## TODO list
@@ -41,6 +53,10 @@ An overview of all the changes made to this codebase can be found in the [CHANGE
 * [x] add unit tests to the code to make this package more maintainable
 * [x] make glossary file name/location configurable, see [feature request #1](https://github.com/TheGreenToaster/docsify-glossary/issues/1)
 * [x] make terminology heading depth configurable, see [feature request #1](https://github.com/TheGreenToaster/docsify-glossary/issues/1)
-* [ ] fix issue with terminology replacements in page headers/titles, see: [bug report #6](https://github.com/TheGreenToaster/docsify-glossary/issues/6)
+* [x] fix issue with terminology replacements in page headers/titles, see: [bug report #6](https://github.com/TheGreenToaster/docsify-glossary/issues/6)
 * [ ] fix issue with terminology replacements in code blocks, see: [bug report #4](https://github.com/TheGreenToaster/docsify-glossary/issues/4)
-* [ ] fix issue with multiple word terms, see: [bug report #13]([bug report #13](https://github.com/TheGreenToaster/docsify-glossary/issues/13))
+* [x] fix issue with multiple word terms, see: [bug report #13]([bug report #13](https://github.com/TheGreenToaster/docsify-glossary/issues/13))
+
+
+1. copy the latest version of the code into the example website: `cp ./dist/@stijn-dejongh/docsify-glossary* ./example`
+2. Run `docsify serve example`

example/docsify-glossary.js

@@ -9,20 +9,33 @@ this["@stijn-dejongh/docsify-glossary"] = this["@stijn-dejongh/docsify-glossary"
 
 this["@stijn-dejongh/docsify-glossary"].js = function(exports) {
     "use strict";
-    function replaceTerm(term, content, term_id) {
-        var link = " [$1](/_glossary?id=".concat(term_id, ")");
-        var re = new RegExp("\\s(".concat(term, ")\\s"), "ig");
+    function replaceTermInLine(term, contentLine, linkId) {
+        var re = new RegExp("\\s(".concat(term, ")[\\s$]"), "ig");
         var reFullStop = new RegExp("\\s(".concat(term, ")."), "ig");
         var reComma = new RegExp("\\s(".concat(term, "),"), "ig");
-        return content.replace(reComma, link + ",").replace(re, link + " ").replace(reFullStop, link + ".");
+        var link = " [$1](/_glossary?id=".concat(linkId, ")");
+        var replacement = contentLine.replace(reComma, link + ",").replace(re, link + " ").replace(reFullStop, link + ".");
+        return isTitle(contentLine) ? replacement.replaceAll("[".concat(term, "]"), "[ ".concat(term, "]")) : replacement;
+    }
+    function isTitle(line) {
+        return line.trim().startsWith("#");
+    }
+    function replaceTerm(content, term, linkId) {
+        var contentLines = content.split("\n");
+        var processedText = "";
+        contentLines.forEach((function(line, _index) {
+            var replacedLine = line.trim().length > 0 ? replaceTermInLine(term, line + " ", linkId).trimEnd() : line;
+            processedText += replacedLine + "\n";
+        }));
+        return processedText;
     }
     function addLinks(content, terms, config) {
         var textWithReplacements = content;
         if (config.debug) {
             console.log("Adding links for terminology: ".concat(terms));
         }
         for (var term in terms) {
-            textWithReplacements = replaceTerm(term, textWithReplacements, terms[term]);
+            textWithReplacements = replaceTerm(textWithReplacements, term, terms[term]);
         }
         return textWithReplacements;
     }

example/docsify-glossary.min.js

@@ -5,7 +5,7 @@ export class GlossaryConfigurationBuilder {
     terminologyHeading = '';
     glossaryLocation = '';
     debug = false;
-
+    replaceTitleTerms = true;
     constructor() {
         this.terminologyHeading = DEFAULT_TERM_HEADING;
         this.glossaryLocation = DEFAULT_GLOSSARY_FILE_NAME;
@@ -26,6 +26,11 @@ export class GlossaryConfigurationBuilder {
         return this;
     }
 
+    withTitleTermReplacement(enableTitleTermReplacement) {
+        this.replaceTitleTerms = enableTitleTermReplacement;
+        return this;
+    }
+
     build() {
         return {...this};
     }
@@ -36,6 +41,7 @@ export function configFromYaml(configurationYaml) {
             .withTermHeading(configurationYaml.terminologyHeading ?? DEFAULT_TERM_HEADING)
             .withGlossaryLocation(configurationYaml.glossaryLocation ?? DEFAULT_GLOSSARY_FILE_NAME)
             .withDebugEnabled(configurationYaml.debug ?? false)
+            .withTitleTermReplacement(configurationYaml.replaceTitleTerms ?? true)
             .build();
 }
 

src/main/js/configuration.js

@@ -1,14 +1,36 @@
-export function replaceTerm(term, content, term_id) {
-    let link = ` [$1](/_glossary?id=${term_id})`;
+function replaceTermInLine(term, contentLine, linkId, config) {
+    if(isTitle(contentLine) && !config.replaceTitleTerms) {
+        // Intentially not combined in the return statement, to avoid superfluous calculations
+        return contentLine;
+    }
+
+    let re = new RegExp(`\\s(${term})[\\s$]`, 'ig');
 
-    let re = new RegExp(`\\s(${term})\\s`, 'ig');
     let reFullStop = new RegExp(`\\s(${term}).`, 'ig');
     let reComma = new RegExp(`\\s(${term}),`, 'ig');
 
-    return content
-            .replace(reComma, link + ',')
+    let link = ` [$1](/_glossary?id=${linkId})`;
+
+    let replacement = contentLine.replace(reComma, link + ',')
             .replace(re, link + ' ')
             .replace(reFullStop, link + '.');
+
+    return isTitle(contentLine) ? replacement.replaceAll(`[${term}]`, `[ ${term}]`): replacement;
+}
+
+function isTitle(line) {
+    return line.trim().startsWith('#');
+}
+
+export function replaceTerm(content, term, linkId, config) {
+    let contentLines = content.split('\n');
+    let processedText = '';
+
+    contentLines.forEach( (line, _index) => {
+        let replacedLine = line.trim().length > 0 ? replaceTermInLine(term, line + ' ', linkId, config).trimEnd() : line;
+        processedText += replacedLine + '\n';
+    });
+    return processedText;
 }
 
 export function addLinks(content, terms, config) {
@@ -17,7 +39,7 @@ export function addLinks(content, terms, config) {
         console.log(`Adding links for terminology: ${terms}`);
     }
     for (let term in terms) {
-        textWithReplacements = replaceTerm(term, textWithReplacements, terms[term]);
+        textWithReplacements = replaceTerm(textWithReplacements, term, terms[term], config);
     }
     return textWithReplacements;
 }

src/main/js/glossary.js

@@ -96,5 +96,32 @@ describe('Glossary terminology injection', () => {
 
         expect([...result.matchAll('/_glossary\\?id=api')]).toHaveLength(5);
     });
+
+    it('preserves spaces in title sequences', () => {
+        const textWithTitle = `
+          ## Information about the API
+          
+          Some API is configured to use another API.
+      `;
+
+        const result = addLinks(textWithTitle, dictionary, config);
+
+        expect(result).toContain('## Information about the [ API](/_glossary?id=api)');
+    });
+
+    it('Word replacement in title sequences can be disabled', () => {
+        const textWithTile = `
+            # This is an API title
+            
+            This is a paragraph of text, explaing stuff and mentioning the term API.
+       `;
+
+        const configuration = glossifyConfig().withTitleTermReplacement(false)
+                .build();
+
+        let result = addLinks(textWithTile, dictionary, configuration);
+
+        expect(result).toContain('# This is an API title');
+    });
 });