fix(docs): Make docs compatible with Hugo 0.7

Closes #339

docs/README.md

@@ -4,15 +4,15 @@ This is the source for the Vendure documentation website. Docs are written in ma
 
 ## Building the docs
 
-To build the docs, first [install Hugo](https://gohugo.io/getting-started/installing/) on your machine.
-
-The run the `docs:build` script from the root of this repo.
+1. [Install Hugo](https://gohugo.io/getting-started/installing/) on your machine. Currently, the live docs are built with **Hugo v0.7**.
+2. Install docs dependencies by running `yarn install` or `npm install` in this directory.
+3. Then run the `docs:build` script from the root of this repo.
 
 This task will:
 
-1. Auto-generate the API markdown files based on the Vendure server source (see below)
-2. Run webpack to build the JavaScript and CSS for the docs site
-3. Run Hugo to build and output the site into the `docs/public` directory.
+* Auto-generate the API markdown files based on the Vendure server source (see below)
+* Run webpack to build the JavaScript and CSS for the docs site
+* Run Hugo to build and output the site into the `docs/public` directory.
 
 ## Dev mode
 

docs/assets/scripts/toc-highlighter.ts

@@ -2,39 +2,44 @@
  * Highlights the current section in the table of contents when scrolling.
  */
 export class TocHighlighter {
-
     constructor(private tocElement: HTMLElement) {}
 
     highlight() {
         const article = document.querySelector('article');
         if (this.tocElement && article) {
-            const headers: HTMLHeadingElement[] = Array.from(article.querySelectorAll('h1[id],h2[id],h3[id],h4[id]'));
+            const headers: HTMLHeadingElement[] = Array.from(
+                article.querySelectorAll('h1[id],h2[id],h3[id],h4[id]'),
+            );
 
             window.addEventListener('scroll', (e) => {
                 this.highlightCurrentSection(headers);
             });
             this.highlightCurrentSection(headers);
         }
-
     }
 
     private highlightCurrentSection(headers: HTMLElement[]) {
         const locationHash = location.hash;
-        Array.from(this.tocElement.querySelectorAll('.active')).forEach(el => el.classList.remove('active'));
+        Array.from(this.tocElement.querySelectorAll('.active')).forEach((el) =>
+            el.classList.remove('active'),
+        );
 
         // tslint:disable:prefer-for-of
         for (let i = 0; i < headers.length; i++) {
             const header = headers[i];
             const nextHeader = headers[i + 1];
             const id = header.getAttribute('id') as string;
-            if (!nextHeader || (nextHeader && (window.scrollY + window.innerHeight - 200) < nextHeader.offsetTop)) {
+            if (
+                !nextHeader ||
+                (nextHeader && window.scrollY + window.innerHeight - 200 < nextHeader.offsetTop)
+            ) {
                 this.highlightItem(id);
                 return;
             }
 
             const isCurrentTarget = `#${id}` === locationHash;
             const currentTargetOffset = isCurrentTarget ? 90 : 0;
-            if ((header.offsetTop + currentTargetOffset) >= window.scrollY) {
+            if (header.offsetTop + currentTargetOffset >= window.scrollY) {
                 this.highlightItem(id);
                 return;
             }
@@ -45,21 +50,22 @@ export class TocHighlighter {
         const tocItem = this.tocElement.querySelector(`[href="#${id}"]`) as HTMLAnchorElement;
         if (tocItem) {
             tocItem.classList.add('active');
-        }
-        // ensure the highlighted item is scrolled into view in the TOC menu
-        const padding = 12;
-        const tocHeight = this.tocElement.offsetHeight;
-        const tocScrollTop = this.tocElement.scrollTop;
-        const outOfRangeTop = tocItem.offsetTop < (tocScrollTop + padding);
-        const outofRangeBottom = tocHeight + tocScrollTop < (tocItem.offsetTop + padding);
-        if (outOfRangeTop) {
-            // console.log('¬TOP');
-            this.tocElement.scrollTo({ top: tocItem.offsetTop - (tocItem.offsetHeight) - padding });
-        }
-        if (outofRangeBottom) {
-            // console.log('$BOTTOm');
-            const delta = tocItem.offsetTop - (tocHeight + tocScrollTop);
-            this.tocElement.scrollTo({ top: tocScrollTop + delta + tocItem.offsetHeight + padding });
+
+            // ensure the highlighted item is scrolled into view in the TOC menu
+            const padding = 12;
+            const tocHeight = this.tocElement.offsetHeight;
+            const tocScrollTop = this.tocElement.scrollTop;
+            const outOfRangeTop = tocItem?.offsetTop < tocScrollTop + padding;
+            const outofRangeBottom = tocHeight + tocScrollTop < tocItem.offsetTop + padding;
+            if (outOfRangeTop) {
+                // console.log('¬TOP');
+                this.tocElement.scrollTo({ top: tocItem.offsetTop - tocItem.offsetHeight - padding });
+            }
+            if (outofRangeBottom) {
+                // console.log('$BOTTOm');
+                const delta = tocItem.offsetTop - (tocHeight + tocScrollTop);
+                this.tocElement.scrollTo({ top: tocScrollTop + delta + tocItem.offsetHeight + padding });
+            }
         }
     }
 }

docs/config.toml

@@ -14,4 +14,7 @@ disableKinds = [
     BookSection = "docs"
 [permalinks]
     blog = "/blog/:year/:month/:slug/"
-
+[markup]
+  [markup.tableOfContents]
+    endLevel = 3
+    startLevel = 1

docs/layouts/docs/list.html

@@ -2,13 +2,11 @@
 <article class="markdown">
     {{ partial "breadcrumbs" . }}
     {{- .Content -}}
-    {{ $list := .Sections }}
-    {{ $list = $list | append .Pages }}
 
-    {{ if gt (len $list) 0 }}
+    {{ if gt (len .Pages) 0 }}
     <h3>Contents:</h3>
     <ul class="contents-list">
-        {{ range $list.ByParam "title" }}
+        {{ range .Pages.ByParam "title" }}
         <li>
             <a href="{{ .RelPermalink }}">{{ .Title }}</a>
         </li>

docs/layouts/partials/docs/menu-filetree.html

@@ -7,9 +7,7 @@
 
 {{ define "book-section" }} <!-- Single section of menu (recursive) -->
 <ul {{ if .Expanded }}class="expanded"{{ end }}>
-    {{ $list := .Section.Sections }}
-    {{ $list = $list | append .Section.Pages }}
-    {{ range ($list.ByParam "Title").ByParam "Weight" }}
+    {{ range (.Section.Pages.ByParam "Title").ByParam "Weight" }}
         {{ if and (eq .Kind "section") (or (gt (len .Pages) 0) (gt (len .Sections) 0) ) }}
             <li class="section">
                 {{ $expanded := in $.CurrentPage .Permalink }}

scripts/docs/typescript-docs-parser.ts

@@ -389,11 +389,10 @@ export class TypescriptDocsParser {
     }
 
     /**
-     * Cleans up a JSDoc "@example" block by removing leading whitespace and asterisk (TypeScript has an open issue
-     * wherein the asterisks are not stripped as they should be, see https://github.com/Microsoft/TypeScript/issues/23517)
+     * Ensure all the code examples use the unix-style line separators.
      */
     private formatExampleCode(example: string = ''): string {
-        return '\n\n*Example*\n\n' + example.replace(/\n\s+\*\s/g, '\n');
+        return '\n\n*Example*\n\n' + example.replace(/\r/g, '\n');
     }
 
     private kebabCase<T extends string | undefined>(input: T): T {