Merge branch 'master' into fix/win-paths

Author: ShukantPal

common/config/rush/version-policies.json

@@ -2,7 +2,7 @@
   {
    "definitionName": "lockStepVersion",
    "policyName": "webdoc",
-   "version": "1.3.1",
+   "version": "1.3.2",
    "nextBump": "patch"
   }
 ]

example/package.json

@@ -34,7 +34,7 @@
     "url": "https://github.com/SukantPal/webdoc/issues"
   },
   "dependencies": {
-    "@webdoc/cli": "^1.3.1"
+    "@webdoc/cli": "^1.3.2"
   },
   "gitHead": "a2866c1a42f60180a74add7bc1b0f42d8bb16330",
   "devDependencies": {

packages/webdoc-cli/CHANGELOG.json

@@ -1,6 +1,18 @@
 {
   "name": "@webdoc/cli",
   "entries": [
+    {
+      "version": "1.3.2",
+      "tag": "@webdoc/cli_v1.3.2",
+      "date": "Sat, 01 May 2021 23:21:56 GMT",
+      "comments": {
+        "none": [
+          {
+            "comment": "Add configuration for custom app bar items and overriding the route for tutorials in @webdoc/default-template"
+          }
+        ]
+      }
+    },
     {
       "version": "1.3.1",
       "tag": "@webdoc/cli_v1.3.1",

packages/webdoc-cli/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Change Log - @webdoc/cli
 
-This log was last generated on Sun, 25 Apr 2021 21:01:31 GMT and should not be manually modified.
+This log was last generated on Sat, 01 May 2021 23:21:56 GMT and should not be manually modified.
+
+## 1.3.2
+Sat, 01 May 2021 23:21:56 GMT
+
+### Updates
+
+- Add configuration for custom app bar items and overriding the route for tutorials in @webdoc/default-template
 
 ## 1.3.1
 Sun, 25 Apr 2021 21:01:31 GMT

packages/webdoc-cli/README.md

@@ -93,6 +93,17 @@ The `template` object is used by the site template.
 {
   "template": {
     "applicationName": "{ <i>webdoc</i> }",
+    "appBar": {
+      "items": {
+        "about": {
+          "name": "About Us",
+          "uri": "https://example.com/about-us"
+        }
+      }
+    },
+    "routes": {
+      "tutorials": "/faq"
+    },
     "meta": {
       "og:title": "webdoc",
       "og:description": "webdoc API documentation",
@@ -114,6 +125,12 @@ The `template` object is used by the site template.
 ```
 
 * `template.applicationName`: The name of the documented software. This is usually used to fill the app bar and tab title.
+* `template.appBar.items`: This key-value object can be used to configure the items in the app bar. The key is an identifier
+    and to override a built-in item, you'll need to use its specific key (if you're adding more items, the key's specific value
+    won't matter). For example, if you want to show the tutorials as "Guides", you can set `{ "tutorials": { "name": "Guides" } }`. Each
+    item defines a name and URI.
+* `template.routes`: This can be used to override specific routes generated by the template. For example, you can move the
+  `tutorials` to be outputted at "/faq" instead of "/tutorials", if desired.
 * `template.meta`: (optional) This can be used to define the `<meta>` key-value tags. The `{{url}}` variable can be used
   to put in the site URL for each page (you have to provide the `siteDomain` and `siteRoot`).
 * `template.repository`: (optional) This can be used to link documents to their location in the source code. The only supported repository is GitHub.

packages/webdoc-cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webdoc/cli",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "CLI for @webdoc monorepo",
   "bin": {
     "webdoc": "./cli.js"
@@ -40,14 +40,14 @@
     "url": "https://github.com/SukantPal/webdoc/issues"
   },
   "dependencies": {
-    "@webdoc/default-template": "^1.3.1",
-    "@webdoc/externalize": "^1.3.1",
-    "@webdoc/legacy-template": "^1.3.1",
-    "@webdoc/model": "^1.3.1",
-    "@webdoc/parser": "^1.3.1",
-    "@webdoc/plugin-markdown": "^1.3.1",
-    "@webdoc/template-library": "^1.3.1",
-    "@webdoc/types": "^1.3.1",
+    "@webdoc/default-template": "^1.3.2",
+    "@webdoc/externalize": "^1.3.2",
+    "@webdoc/legacy-template": "^1.3.2",
+    "@webdoc/model": "^1.3.2",
+    "@webdoc/parser": "^1.3.2",
+    "@webdoc/plugin-markdown": "^1.3.2",
+    "@webdoc/template-library": "^1.3.2",
+    "@webdoc/types": "^1.3.2",
     "array.prototype.flatmap": "~1.2.3",
     "fs-extra": "^9.0.1",
     "globby": "11.0.0",

packages/webdoc-cli/src/config.js

@@ -32,7 +32,18 @@ type ConfigSchema = {
     template?: string,
   },
   template: {
+    appBar: {
+      items: {
+        [string]: {
+          name: string,
+          uri: string,
+        }
+      }
+    },
     applicationName: string,
+    routes: {
+      tutorials: string,
+    },
     stylesheets: Array<string>,
     siteDomain?: string,
     siteRoot: string,
@@ -78,7 +89,13 @@ const defaultConfig: ConfigSchema = {
     template: "@webdoc/default-template",
   },
   template: {
+    appBar: {
+      items: {},
+    },
     applicationName: "{ <i>webdoc</i> }",
+    routes: {
+      tutorials: "tutorials",
+    },
     siteRoot: "",
     stylesheets: [],
     mainPage: {

packages/webdoc-cli/src/index.js

@@ -61,7 +61,7 @@ async function main(argv: yargs.Argv) {
 
   const {loadConfig, getTemplate} = require("./config");
   const config = loadConfig(argv.config);
-  const tutorials = loadTutorials(argv.tutorials);
+  const tutorials = loadTutorials(argv.tutorials, config.template.routes.tutorials);
 
 
   if (argv.siteRoot) {

packages/webdoc-cli/src/load-tutorials/load-tutorials.js

@@ -17,7 +17,7 @@ const renderer = require("markdown-it")({
   .use(require("markdown-it-highlightjs"));
 
 // Loads & parses all the tutorials in the given directory
-export function loadTutorials(tutorialsDir?: string): Tutorial[] {
+export function loadTutorials(tutorialsDir?: string, tutorialsRoute?: string): Tutorial[] {
   if (!tutorialsDir) {
     return [];
   }
@@ -80,10 +80,12 @@ export function loadTutorials(tutorialsDir?: string): Tutorial[] {
     // Tutorials can be part of the doc-tree!
     tutorials.push(createTutorialDoc(
       fileName,
-      path.join("tutorials", relativePath
-        .replace(".html", "")
-        .replace(".htm", "")
-        .replace(".md", "")),
+      path.join(
+        typeof tutorialsRoute === "string" ? tutorialsRoute : "tutorials",
+        relativePath
+          .replace(".html", "")
+          .replace(".htm", "")
+          .replace(".md", "")),
       fileContent,
     ));
   }

packages/webdoc-default-template/CHANGELOG.json

@@ -1,6 +1,18 @@
 {
   "name": "@webdoc/default-template",
   "entries": [
+    {
+      "version": "1.3.2",
+      "tag": "@webdoc/default-template_v1.3.2",
+      "date": "Sat, 01 May 2021 23:21:56 GMT",
+      "comments": {
+        "none": [
+          {
+            "comment": "Use CSS Grid to fix scrolling issues in Safari. Don't generate README file if not provided. Don't output API reference if document tree is empty (i.e. you're using webdoc to generate a tutorials-only site) Add support for custom app bar items."
+          }
+        ]
+      }
+    },
     {
       "version": "1.3.1",
       "tag": "@webdoc/default-template_v1.3.1",