Merge pull request #64 from webdoc-js/feature/package-prefix

Add packageName prefix in all URLs

Author: ShukantPal

packages/webdoc-cli/src/index.js

@@ -69,6 +69,9 @@ async function main(argv: yargs.Argv) {
   if (config.template.siteRoot[0] === "/") {
     config.template.siteRoot = config.template.siteRoot.slice(1);
   }
+  if (config.template.siteRoot.endsWith("/")) {
+    config.template.siteRoot = config.template.siteRoot.slice(0, -1);
+  }
 
   // TODO: Fix what env/conf is?
   global.Webdoc.env = config;

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

@@ -44,7 +44,7 @@ function buildLinks(tree /*: RootDoc */) /*: void */ {
 }
 
 function buildIndex(tree /*: RootDoc */) /*: [id: string]: [] & { url: string } */ {
-  const classIndexUrl = linker.createURI("Class-Index");
+  const classIndexUrl = linker.createURI("Class-Index", true);
 
   const index /*: [id: string]: [] & { url: string } */ = {
     classes: [],

packages/webdoc-default-template/publish.js

@@ -52,7 +52,7 @@ exports.publish = (options /*: PublishOptions */) => {
   const docTree = options.documentTree;
   const outDir = path.normalize(options.config.opts.destination);
   const index = linker.createURI("index");
-  const indexRelative = index.slice(linker.siteRoot.length + 1);
+  const indexRelative = index.replace(`/${linker.siteRoot}/`, "");
 
   fse.ensureDir(outDir);
 
@@ -173,18 +173,13 @@ 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];
-    let url = indexList.url;
-
-    if (url.startsWith(siteRoot)) {
-      url = url.slice(siteRoot.length);
-    }
+    const url = linker.processInternalURI(indexList.url, {outputRelative: true});
 
     pipeline.render("pages/api-index.tmpl", {
       documentList: indexList,
@@ -206,17 +201,16 @@ function outReference(
   config /*: WebdocConfig */,
   docTree, /*: RootDoc */
 ) {
-  const siteRoot = `/${config.template.siteRoot}`;
-
   for (const [id, docRecord] of linker.documentRegistry) {
     let {uri: page} = docRecord;
 
     if (page.includes("#")) {
       continue;// skip fragments (non-standalone docs)
     }
-    if (page.startsWith(siteRoot)) {
-      page = page.slice(siteRoot.length);
-    }
+
+    page = linker.processInternalURI(page, {outputRelative: true});
+
+    console.log(page);
 
     let doc;
 

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

@@ -260,7 +260,7 @@ function LinkerPluginShell() {
 
         const rec = this.documentRegistry.get(doc.id);
 
-        fileUrl = rec ? rec.uri : this.getURI(doc);
+        fileUrl = rec && rec.uri ? this.processInternalURI(rec.uri) : this.getURI(doc);
 
         // Cache this query
         if (fileUrl) {
@@ -334,9 +334,10 @@ function LinkerPluginShell() {
      * wasn't already.
      *
      * @param {Doc} doc
+     * @param {boolean} outputRelative
      * @return {string}
      */
-    getURI(doc: Doc): string {
+    getURI(doc: Doc, outputRelative?: boolean): string {
       const id = doc.id;
 
       const record = this.getDocumentRecord(id);
@@ -347,14 +348,31 @@ function LinkerPluginShell() {
         record.uri = uri;
       }
 
-      return uri;
+      return this.processInternalURI(uri, {outputRelative});
     }
 
-    createURI(preferredUri: string): string {
+    createURI(preferredUri: string, outputRelative?: boolean): string {
       const uri = this.generateBaseURI(preferredUri);
 
       this.getFileRecord(uri);
 
+      return this.processInternalURI(uri, {outputRelative});
+    }
+
+    /**
+     * Replaces variables like <siteRoot/> in the URI.
+     *
+     * @param {string} uri
+     * @param {object} options
+     * @return {string} uri with siteRoot
+     */
+    processInternalURI(uri: string, options: { outputRelative?: boolean } = {}): string {
+      if (!options.outputRelative) {
+        uri = uri.replace("%3CsiteRoot%3E", this.siteRoot);
+      } else {
+        uri = uri.replace("/%3CsiteRoot%3E/", "");
+      }
+
       return uri;
     }
 
@@ -369,27 +387,29 @@ function LinkerPluginShell() {
      *
      * @private
      * @param {string} canonicalPath - The canonical
+     * @param {string} pathPrefix - The folder path inside which to place the document, if desired.
      * @return {string} The filename to use for the string.
      */
-    generateBaseURI(canonicalPath: string): string {
+    generateBaseURI(canonicalPath: string, pathPrefix: string = ""): string {
       let seedURI = (canonicalPath || "")
         // use - instead of : in namespace prefixes
         // replace characters that can cause problems on some filesystems
-        .replace(/[\\/?*:|'"<>]/g, "_")
+        .replace(/[\\?*:|'"<>]/g, "_")
         // use - instead of ~ to denote 'inner'
         .replace(/~/g, "-")
         // use _ instead of # to denote 'instance'
         .replace(/#/g, "_")
-        // use _ instead of / (for example, in module names)
-        .replace(/\//g, "_")
         // remove the variation, if any
         .replace(/\([\s\S]*\)$/, "")
         // make sure we don't create hidden files, or files whose names start with a dash
         .replace(/^[.-]/, "");
 
       if (this.fileLayout === "tree") {
         seedURI = seedURI.replace(/[.]/g, "/");
-        seedURI = "/" + path.join(this.siteRoot, seedURI);
+        seedURI = path.join("/<siteRoot>", pathPrefix, seedURI);
+      } else {
+        // use _ instead of / (for example, in module names)
+        seedURI = seedURI.replace(/\//g, "_");
       }
 
       // in case we've now stripped the entire basename (uncommon, but possible):
@@ -416,7 +436,7 @@ function LinkerPluginShell() {
         }
       }
 
-      return probeURI;
+      return encodeURI(probeURI);
     }
 
     /**
@@ -476,7 +496,18 @@ function LinkerPluginShell() {
 
       // the doc gets its own HTML file
       if (standaloneDocTypes.includes(doc.type)) {
-        baseURI = this.generateBaseURI(docPath);
+        let pathPrefix = "";
+
+        if (doc.type !== "PackageDoc" && doc.loc) {
+          const pkg = doc.loc.file.package;
+
+          if (pkg) {
+            // Remove extension of package URI and use as folder
+            pathPrefix = this.getURI(pkg, true).split(".").slice(0, -1).join(".");
+          }
+        }
+
+        baseURI = this.generateBaseURI(docPath, pathPrefix);
 
         this.getFileRecord(baseURI);
       } else { // inside another HTML file
@@ -490,7 +521,7 @@ function LinkerPluginShell() {
         );
       }
 
-      return `${encodeURI(baseURI)}${fragment ? "#" + fragment : ""}`;
+      return `${baseURI}${fragment ? "#" + fragment : ""}`;
     }
   }