Add --site-root option and respect that within default template. Use site root in CI

Author: ShukantPal

example/package.json

@@ -23,9 +23,9 @@
   },
   "scripts": {
     "unit-test": "",
-    "build": "webdoc --tutorials ./tutorials",
+    "build": "webdoc --tutorials ./tutorials --site-root example-documentation",
     "build-next": "cd .. && webdoc && cd example",
-    "build-pixi-api": "cd ../../pixi-api && webdoc && cd ../webdoc/example"
+    "build-pixi-api": "cd ../../pixi-api && webdoc --site-root docs && cd ../webdoc/example"
   },
   "bugs": {
     "url": "https://github.com/SukantPal/webdoc/issues"

packages/webdoc-cli/src/config.js

@@ -27,7 +27,8 @@ type ConfigSchema = {
     export?: string,
     template?: string,
   },
-  template?: {
+  template: {
+    siteRoot: string,
     mainPage?: {
       title?: string
     },
@@ -69,6 +70,7 @@ const defaultConfig: ConfigSchema = {
     template: "@webdoc/default-template",
   },
   template: {
+    siteRoot: "",
     mainPage: {
       title: "Main Page",
     },

packages/webdoc-cli/src/index.js

@@ -63,6 +63,13 @@ async function main(argv: yargs.Argv) {
   const config = loadConfig(argv.config);
   const tutorials = loadTutorials(argv.tutorials);
 
+  if (argv.siteRoot) {
+    config.template.siteRoot = argv.siteRoot;
+  }
+  if (config.template.siteRoot[0] === "/") {
+    config.template.siteRoot = config.template.siteRoot.slice(1);
+  }
+
   // TODO: Fix what env/conf is?
   global.Webdoc.env = config;
   // $FlowFixMe
@@ -143,7 +150,7 @@ async function main(argv: yargs.Argv) {
 }
 
 const argv = yargs.scriptName("@webdoc/cli")
-  .usage("$0 -c <configFile> -u <tutorialDir> --verbose")
+  .usage("$0 -c <configFile> -u <tutorialDir> --verbose --site-root <siteRoot>")
   .default("config", path.join(process.cwd(), "webdoc.conf.json"), "webdoc config file")
   .alias("c", "config")
   .alias("u", "tutorials")

packages/webdoc-default-template/helper/crawl/crawl-reference-explorer.js

@@ -30,19 +30,18 @@ const HINTS = {
 };
 
 // Crawls the tree searching for the API reference
-function crawlReference(doc /*: Doc */) {
+function crawlReference(doc /*: Doc */, index /*: string */) {
   const explorerHierarchy =
     buildExplorerHierarchy(doc, doc.packages ? (doc.packages.length > 1) : false);
-
-  const tree = buildExplorerTargetsTree(explorerHierarchy);
+  const tree = buildExplorerTargetsTree(explorerHierarchy, "", index);
 
   return tree;
 }
 
 exports.crawlReference = crawlReference;
 
 function getPage(doc /*: Doc */) {
-  return "/" + linker.getURI(doc);
+  return linker.getURI(doc);
 }
 
 /*::
@@ -159,9 +158,10 @@ function traversePackage(doc /*: Doc | PackageDoc */, context /*: Object */, par
 function buildExplorerTargetsTree(
   node /*: ExplorerNode */,
   parentTitle /*: string */ = "",
+  index /*: string */,
 ) /*: ExplorerTarget */ {
   const doc = node.doc;
-  const page = doc.type !== "RootDoc" ? getPage(doc) : "/index.html";
+  const page = doc.type !== "RootDoc" ? getPage(doc) : index;
 
   let title = "";
 
@@ -187,16 +187,16 @@ function buildExplorerTargetsTree(
     };
 
     if (node.doc.type === "RootDoc") {
-      node.children["(overview)"].page = "/index.html";
+      node.children["(overview)"].page = index;
 
       node.children.ClassIndex = {
         title: "Class Index",
-        page: "/" + linker.createURI("Class-Index"),
+        page: linker.createURI("Class-Index"),
       };
     }
 
     for (const [, value] of Object.entries(childNodes)) {
-      const children = value.map((cn) => buildExplorerTargetsTree(cn, title));
+      const children = value.map((cn) => buildExplorerTargetsTree(cn, title, index));
 
       children.forEach((child) => {
         node.children[child.title] = child;

packages/webdoc-default-template/helper/crawl/crawl.js

@@ -20,12 +20,12 @@ export type CategorizedDocumentList = {
 */
 
 
-exports.crawl = function crawl(tree /*: RootDoc */) {
+exports.crawl = function crawl(tree /*: RootDoc */, index /*: string */) {
   buildLinks(tree);
 
   return {
     index: buildIndex(tree),
-    reference: crawlReference(tree),
+    reference: crawlReference(tree, index),
   };
 };
 

packages/webdoc-default-template/publish.js

@@ -45,13 +45,17 @@ const PRETTIFIER_SCRIPT_FILES = [
 let idToDoc/*: Map<string, Doc> */;
 
 exports.publish = (options /*: PublishOptions */) => {
+  const config = options.config;
+
+  linker.siteRoot = config.template.siteRoot;
+
   const docTree = options.documentTree;
   const outDir = path.normalize(options.config.opts.destination);
   const index = linker.createURI("index");
 
   fse.ensureDir(outDir);
 
-  const crawlData = crawl(docTree);
+  const crawlData = crawl(docTree, index);
   const renderer = new TemplateRenderer(path.join(__dirname, "tmpl"), null, docTree)
     .setLayoutTemplate("layout.tmpl")
     .installPlugin("linker", linker)
@@ -168,13 +172,18 @@ function outIndexes(
   config /*: WebdocConfig */,
   index, /*: Index */
 ) {
+  const siteRoot = `/${config.template.siteRoot}`;
   const KEY_TO_TITLE = {
     "classes": "Class Index",
   };
 
   function outIndex(indexKey, indexList) {
     const title = KEY_TO_TITLE[indexKey];
-    const url = indexList.url;
+    let url = indexList.url;
+
+    if (url.startsWith(siteRoot)) {
+      url = url.slice(siteRoot.length);
+    }
 
     pipeline.render("pages/api-index.tmpl", {
       documentList: indexList,
@@ -196,12 +205,17 @@ function outReference(
   config /*: WebdocConfig */,
   docTree, /*: RootDoc */
 ) {
+  const siteRoot = `/${config.template.siteRoot}`;
+
   for (const [id, docRecord] of linker.documentRegistry) {
-    const {uri: page} = docRecord;
+    let {uri: page} = docRecord;
 
     if (page.includes("#")) {
       continue;// skip fragments (non-standalone docs)
     }
+    if (page.startsWith(siteRoot)) {
+      page = page.slice(siteRoot.length);
+    }
 
     let doc;
 

packages/webdoc-default-template/src/app/components/Explorer/index.js

@@ -12,7 +12,7 @@ export default function Explorer(props) {
   const children = [];
 
   if (!fetched) {
-    fetch("/explorer/reference.json")
+    fetch("/" + window.appData.siteRoot + "/explorer/reference.json")
       .then((response) => {
         if (response.ok) {
           response.json().then((idata) => {

packages/webdoc-default-template/static/scripts/default-template.js

@@ -4970,7 +4970,7 @@ function Explorer(props) {
   var children = [];
 
   if (!fetched) {
-    fetch("/explorer/reference.json").then(function (response) {
+    fetch("/" + window.appData.siteRoot + "/explorer/reference.json").then(function (response) {
       if (response.ok) {
         response.json().then(function (idata) {
           setData(idata || {});

packages/webdoc-default-template/tmpl/layout.tmpl

@@ -2,22 +2,28 @@
 /**
  * Global layout render component.
  */
-const rootData = obj
+const rootData = obj;
+const siteRoot = this.getPlugin("linker").siteRoot;
 ?>
 <!DOCTYPE html>
 <html lang="en">
   <head>
     <meta charset="utf-8" />
     <title>webdoc: <?js= title ?></title>
 
-    <link type="text/css" rel="stylesheet" href="/styles/index.css" />
+    <link type="text/css" rel="stylesheet" href="/<?js= siteRoot ?>/styles/index.css" />
     <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,500,700&display=swap" />
     <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto+Mono:300,400,500,700&display=swap" />
     <link type="text/css" rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/10.0.3/styles/googlecode.min.css">
 
     <script crossorigin src="https://unpkg.com/react@16/umd/react.development.js"></script>
     <script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.development.js"></script>
-    <script src="/scripts/default-template.js"></script>
+    <script>
+      window.appData = {
+        siteRoot: "<?js= siteRoot ?>",
+      };
+    </script>
+    <script src="/<?js= siteRoot ?>/scripts/default-template.js"></script>
   </head>
   <body class="root">
     <div class="docs">

packages/webdoc-template-library/src/template-plugins/LinkerPlugin.js

@@ -31,6 +31,7 @@ export type FileLayout = "linear" | "tree";
 function LinkerPluginShell() {
   // TODO: Replace catharsis with a in-built @webdoc/data-type-parser
   const catharsis = require("catharsis");
+  const path = require("path");
   const {query} = require("@webdoc/model");
   const {MixinPlugin} = require("./MixinPlugin");
 
@@ -114,6 +115,11 @@ function LinkerPluginShell() {
      */
     fileRegistry = new Map<string, LinkerFileRecord>();
 
+    /**
+     * The site root path, used to for absolute linking.
+     */
+    siteRoot = "";
+
     /**
      * Cache of DPL queries to their URIs.
      */
@@ -383,6 +389,7 @@ function LinkerPluginShell() {
 
       if (this.fileLayout === "tree") {
         seedURI = seedURI.replace(/[.]/g, "/");
+        seedURI = "/" + path.join(this.siteRoot, seedURI);
       }
 
       // in case we've now stripped the entire basename (uncommon, but possible):