New webRoot variable for relative links

center-key · Oct 7, 2023 · 693b00c · 693b00c
1 parent 020434f
commit 693b00c
Show file tree

Hide file tree

Showing 13 changed files with 115 additions and 21 deletions.
diff --git a/README.md b/README.md
@@ -85,48 +85,54 @@ Escape characters:
 ### 4. Example CLI usage
 Examples:
    - `replacer src build`<br>
-   Recursively copy all the files in the **src** folder to the **build** folder using the data in **package.json** to update the template outputs.
+   Recursively copies all the files in the **src** folder to the **build** folder using the data in **package.json** to update the template outputs.
 
    - `replacer src/docs --ext=.md --find=Referer --replacement=Referrer output/fixed`<br>
-   Fix spelling error in markdown files.
+   Fixes spelling error in markdown files.
 
    - `replacer src/docs --ext=.md --find=Referer --replacement=Referrer --no-liquid output/fixed`<br>
-   Same as previous example but disable LiquidJS templating (useful in case source files contain characters inadvertenly interpreted at templating commands).
+   Same as previous example but disables LiquidJS templating (useful in case source files contain characters inadvertently interpreted at templating commands).
 
    - `replacer web '--find=cat dog' '--replacement= cat{{pipe}}dog ' target`<br>
    `replacer web --find=cat\ dog --replacement=\ cat{{pipe}}dog\  target`<br>
    `replacer web --find=cat{{space}}dog --replacement={{space}}cat{{pipe}}dog{{space}} target`<br>
-   Replace all occurances of the string `'cat dog'` with `' cat|dog '` (note the _3 different_ ways to _"escape"_ a space character).
+   Replaces all occurances of the string `'cat dog'` with `' cat|dog '` (note the _3 different_ ways to _"escape"_ a space character).
 
-   - `replacer src --ext=.js --concat=bundle.js build`<br>
-   Merge all JS files into **build/bundle.js**.
+   - `replacer src --ext=.js --no-liquid --concat=bundle.js build`<br>
+   Merges all JS files into **build/bundle.js**.
 
    - `replacer app/widgets --ext=.less --content=@import{{space}}{{quote}}{{file.dir}}/{{file.name}}{{quote}}{{semi}} --concat=widgets.less app/style`<br>
-   Create a single LESS file that imports the LESS files of every widget component.
+   Creates a single LESS file that imports the LESS files of every widget component.
 
    - `replacer src --summary build`<br>
-   Display the summary but not the individual files copied.
+   Displays the summary but not the individual files copied.
 
    - `replacer src --regex=/^--/gm --replacement=🥕🥕🥕 build`<br>
-   Find double dashes at the start of lines and replace them with 3 carrots.&nbsp;
+   Finds double dashes at the start of lines and replace them with 3 carrots.&nbsp;
    Note the `gm` [regex options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions#advanced_searching_with_flags).
 
    - `replacer build/my-app.js --rename=my-app.browser.js build`<br>
-   Copy **my-app.js** to **my-app.browser.js** without making and changes.
+   Copies **my-app.js** to **my-app.browser.js** without making and changes.
 
    - `replacer src/web --ext=.html --rename=index.html dist/website`<br>
-   Rename all HTML files, such as **src/web/about/about.html**, to **index.html** while preserving the folder stucture.
+   Renames all HTML files, such as **src/web/about/about.html**, to **index.html** while preserving the folder structure.
 
    - `replacer --cd=spec/fixtures source --find=insect --replacement=A.I. target`<br>
-   Remove all insects.  See: [source/mock1.html](spec/fixtures/source/mock1.html) and [target/mock1.html](spec/fixtures/target/mock1.html)
+   Removes all insects.  See: [source/mock1.html](spec/fixtures/source/mock1.html) and [target/mock1.html](spec/fixtures/target/mock1.html)
 
    - `replacer node_modules/chart.js/dist/chart.umd.js --no-source-map build/1-pre/libs`<br>
    Removes the `//# sourceMappingURL=chart.umd.js.map` line at the bottom of the **Chart.js** distribution file.
 
+_**Note:** Single quotes in commands are normalized so they work cross-platform and avoid the errors often encountered on Microsoft Windows._
+
 ### 5. Template outputs and filter formatters
 The source files are processed by LiquidJS, so you can use [template outputs](https://liquidjs.com/tutorials/intro-to-liquid.html#Outputs) and [filter formatters](https://liquidjs.com/filters/overview.html).&nbsp;
-The values from your project's **package.json** file are available as fields of the `package` variable.&nbsp;
-In addition to the `package` variable, [path information](https://nodejs.org/api/path.html#pathparsepath) is available in the `file` variable (which also includes the supplemental `path` field).
+Custom variables are created with the [assign](ttps://liquidjs.com/tags/assign.html) tag.
+
+Three special variables are available by default:
+   * `file`    ([path information](https://nodejs.org/api/path.html#pathparsepath) about the target file)
+   * `package` (values from your project's **package.json** file)
+   * `webRoot` (relative path to root folder: `.`, `..`, `../..`, `../../..`, etc.)
 
 For example, a TypeScript file with the lines:
 ```typescript
@@ -142,15 +148,16 @@ const msg2: string = 'This file is: my-app.ts';
 Example outputs and formatters:
 | Source file text               | Example output value      | Note                                           |
 | ------------------------------ | ------------------------- | ---------------------------------------------- |
-| `{{package.name}}`             | `my-project`              | Value from `name` field in **pacakge.json**    |
-| `{{package.version}}`          | `3.1.4`                   | Value from `version` field in **pacakge.json** |
+| `{{package.name}}`             | `my-project`              | Value from `name` field in **package.json**    |
+| `{{package.version}}`          | `3.1.4`                   | Value from `version` field in **package.json** |
 | `{{package.version | size}}`   | `5`                       | Length of the version number string            |
 | `{{file.name}}`                | `password-reset`          | Source filename without the file extension     |
 | `{{file.path}}`                | `web/password-reset.html` | Full path to source file                       |
+| `<a href={{webRoot}}>Home</a>` | `<a href=../..>Home</a>`  | Link is relative to the source folder          |
 | `{{"now" | date: "%Y-%m-%d"}}` | `2023-09-28`              | Build date timestamp                           |
 | `{{myVariable | upcase}}`      | `DARK MODE`               | Custom variable set with: `{% assign myVariable = 'dark mode' %}` |
 
-**Note:** Use the `--no-liquid` flag if characters in your source files are inadvertenly being interpreted as templating commands and causing errors.
+_**Note:** Use the `--no-liquid` flag if characters in your source files are inadvertently being interpreted as templating commands and causing errors._
 
 ### 6. SemVer
 Your project's dependancies declared in **package.json** can be used to automatically keep your
@@ -169,9 +176,8 @@ will be transformed into:
 ```html
 <script src=https://cdn.jsdelivr.net/npm/[email protected]/dist/fetch-json.min.js></script>
 ```
-_Note:_ Some package names contain one or more of the characters `@`, `/`, and `.`, and these 3
-characters are not supported for replacement.&nbsp;
-Use `-` in the package name instead.
+_**Note:** Some package names contain one or more of the characters `@`, `/`, and `.`, and these 3
+characters are not supported for replacement.&nbsp; Use `-` in the package name instead._
 
 For example, CDN links for the packages `"@fortawesome/fontawesome-free"` and `"highlight.js"` can be created with:
 ```html

diff --git a/replacer.ts b/replacer.ts
@@ -129,8 +129,16 @@ const replacer = {
          const filePath =   dir + '/' + slash(parsedPath.base);
          return { ...parsedPath, dir: dir, path: filePath };
          };
+      const getWebRoot = (origin: string) => {
+         const depth = origin.substring(source.length).split('/').length - 2;
+         return depth === 0 ? '.' : '..' + '/..'.repeat(depth - 1);
+         };
       const createEngine = (file: ResultsFile) => {
-         const globals = { package: pkg, file: getFileInfo(file.origin) };
+         const globals = {
+            package: pkg,
+            file:    getFileInfo(file.origin),
+            webRoot: getWebRoot(file.origin),
+            };
          globals[<keyof typeof globals>'pkg'] = pkg;  //pkg global is deprecated
          const engine =  new Liquid({ globals });
          const versionFormatter = (numIds: number) =>

diff --git a/spec/fixtures/source/mock1.html b/spec/fixtures/source/mock1.html
@@ -19,5 +19,8 @@ <h2>{{package.description}}</h2>
          <li>Major:   v{{package.version | major-version}}</li>
       </ul>
       <pre><code class=language-js>{% render 'spec/fixtures/source/subfolder-a/mock2.js' %}</code></pre>
+      <footer>
+         <a href={{webRoot}}>Home</a>
+      </footer>
    </body>
 </html>
diff --git a/spec/fixtures/source/subfolder-a/mock2.html b/spec/fixtures/source/subfolder-a/mock2.html
@@ -16,5 +16,8 @@ <h2>{{package.description}}</h2>
          <li>Minor:   v{{package.version | minor-version}}</li>
          <li>Major:   v{{package.version | major-version}}</li>
       </ul>
+      <footer>
+         <a href={{webRoot}}>Home</a>
+      </footer>
    </body>
 </html>
diff --git a/spec/fixtures/source/subfolder-b/mock3.html b/spec/fixtures/source/subfolder-b/mock3.html
@@ -16,5 +16,8 @@ <h2>{{package.description}}</h2>
          <li>Minor:   v{{package.version | minor-version}}</li>
          <li>Major:   v{{package.version | major-version}}</li>
       </ul>
+      <footer>
+         <a href={{webRoot}}>Home</a>
+      </footer>
    </body>
 </html>
diff --git a/spec/fixtures/source/subfolder-b/subfolder-bb/mock4.html b/spec/fixtures/source/subfolder-b/subfolder-bb/mock4.html
@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang=en>
+   <head>
+      <meta charset=utf-8>
+      <title>🔍🔍🔍 {{package.name}} 🔍🔍🔍</title>
+      <link rel=stylesheet href=https://cdn.jsdelivr.net/npm/pretty-print-json@{{package.devDependencies.pretty-print-json|version}}/dist/css/pretty-print-json.css>
+      <script src=https://cdn.jsdelivr.net/npm/pretty-print-json@{{package.devDependencies.pretty-print-json|version}}/dist/pretty-print-json.min.js></script>
+      <script src=https://cdn.jsdelivr.net/npm/fetch-json@{{package.devDependencies.fetch-json|version}}/dist/fetch-json.min.js></script>
+   </head>
+   <body>
+      <header>
+         <h1>🔍🔍🔍 {{package.name}} 🔍🔍🔍</h1>
+         <h2>{{package.description}}</h2>
+      </header>
+      <main>
+         <p>I, for one, welcome our new insect overlords.</p>
+         <ul>
+            <li>Release: v{{package.version | version}}</li>
+            <li>Minor:   v{{package.version | minor-version}}</li>
+            <li>Major:   v{{package.version | major-version}}</li>
+         </ul>
+      </main>
+      <footer>
+         <a href={{webRoot}}>Home</a>
+      </footer>
+   </body>
+</html>
diff --git a/spec/fixtures/target/mock1.html b/spec/fixtures/target/mock1.html
@@ -37,5 +37,8 @@ <h2>Find and replace strings or template outputs in text files (CLI tool designe
 
 export { info2 };
 </code></pre>
+      <footer>
+         <a href=.>Home</a>
+      </footer>
    </body>
 </html>
diff --git a/spec/fixtures/target/subfolder-a/mock2.html b/spec/fixtures/target/subfolder-a/mock2.html
@@ -16,5 +16,8 @@ <h2>Find and replace strings or template outputs in text files (CLI tool designe
          <li>Minor:   v1.2</li>
          <li>Major:   v1</li>
       </ul>
+      <footer>
+         <a href=..>Home</a>
+      </footer>
    </body>
 </html>
diff --git a/spec/fixtures/target/web/index.html b/spec/fixtures/target/web/index.html
@@ -38,5 +38,8 @@ <h2>Find and replace strings or template outputs in text files (CLI tool designe
 export { info2 };
 //# sourceMappingURL=mock2.js.map
 </code></pre>
+      <footer>
+         <a href=.>Home</a>
+      </footer>
    </body>
 </html>
diff --git a/spec/fixtures/target/web/subfolder-a/index.html b/spec/fixtures/target/web/subfolder-a/index.html
@@ -16,5 +16,8 @@ <h2>Find and replace strings or template outputs in text files (CLI tool designe
          <li>Minor:   v1.2</li>
          <li>Major:   v1</li>
       </ul>
+      <footer>
+         <a href=..>Home</a>
+      </footer>
    </body>
 </html>
diff --git a/spec/fixtures/target/web/subfolder-b/index.html b/spec/fixtures/target/web/subfolder-b/index.html
@@ -16,5 +16,8 @@ <h2>Find and replace strings or template outputs in text files (CLI tool designe
          <li>Minor:   v1.2</li>
          <li>Major:   v1</li>
       </ul>
+      <footer>
+         <a href=..>Home</a>
+      </footer>
    </body>
 </html>
diff --git a/spec/fixtures/target/web/subfolder-b/subfolder-bb/index.html b/spec/fixtures/target/web/subfolder-b/subfolder-bb/index.html
@@ -0,0 +1,27 @@
+<!doctype html>
+<html lang=en>
+   <head>
+      <meta charset=utf-8>
+      <title>🔍🔍🔍 replacer-util 🔍🔍🔍</title>
+      <link rel=stylesheet href=https://cdn.jsdelivr.net/npm/[email protected]/dist/css/pretty-print-json.css>
+      <script src=https://cdn.jsdelivr.net/npm/[email protected]/dist/pretty-print-json.min.js></script>
+      <script src=https://cdn.jsdelivr.net/npm/[email protected]/dist/fetch-json.min.js></script>
+   </head>
+   <body>
+      <header>
+         <h1>🔍🔍🔍 replacer-util 🔍🔍🔍</h1>
+         <h2>Find and replace strings or template outputs in text files (CLI tool designed for use in npm scripts)</h2>
+      </header>
+      <main>
+         <p>I, for one, welcome our new insect overlords.</p>
+         <ul>
+            <li>Release: v1.2.3</li>
+            <li>Minor:   v1.2</li>
+            <li>Major:   v1</li>
+         </ul>
+      </main>
+      <footer>
+         <a href=../..>Home</a>
+      </footer>
+   </body>
+</html>
diff --git a/spec/mocha.spec.js b/spec/mocha.spec.js
@@ -117,6 +117,8 @@ describe('Executing the CLI', () => {
          'subfolder-a/index.html',
          'subfolder-b',
          'subfolder-b/index.html',
+         'subfolder-b/subfolder-bb',
+         'subfolder-b/subfolder-bb/index.html',
          ];
       assertDeepStrictEqual(actual, expected);
       });