Allow for customizing the expected root URL of a docs site.

Author: dfreeman

addon/components/docs-header/version-selector/template.hbs

@@ -9,7 +9,7 @@
       <li data-test-id='version'>
         <a {{action 'changeVersion' version}} href='#' class='text-black no-underline flex items-center px-4 py-3 hover:bg-grey-lighter'>
           <span class='w-6 flex'>
-            {{#if (eq version currentVersion)}}
+            {{#if (eq version.name currentVersion.name)}}
               {{svg-jar 'check' height=16 width=16}}
             {{/if}}
           </span>

addon/services/project-version.js

@@ -5,23 +5,9 @@ import { computed } from '@ember/object';
 import { task } from 'ember-concurrency';
 
 export default Service.extend({
-  current: null,
-  root: null,
-
   _loadAvailableVersions: task(function*() {
-    let config = getOwner(this).resolveRegistration('config:environment');
-    let rootURL = config.rootURL;
-    let tag = config['ember-cli-addon-docs'].projectTag;
-    let slash = rootURL.indexOf('/', 1);
-
-    // TODO deal with apps deployed to custom domains, so their pathnames don't have a leading
-    // segmenet for the project name. This will impact this service and the 404 page.
-    this.set('root', rootURL.slice(0, slash));
-    let currentFromURL = rootURL.substring(slash + 1).replace(/\/$/, '');
-    this.set('current', currentFromURL || 'latest'); // dev-time guard. Think of a better way?
-
-    let response = yield fetch(`${this.get('root')}/versions.json`);
-    let json = yield response.ok ? response.json() : [{ name: 'latest', tag, sha: '12345', path: '/' }];
+    let response = yield fetch(`${this.get('root')}versions.json`);
+    let json = yield response.ok ? response.json() : { latest: this.get('currentVersion') };
 
     this.set('versions', Object.keys(json).map(key => {
       let version = json[key];
@@ -32,19 +18,33 @@ export default Service.extend({
   }),
 
   redirectTo(version) {
-    window.location.href = `${this.get('root')}/${version.path || version}`;
+    window.location.href = `${this.get('root')}${version.path}`;
   },
 
   loadAvailableVersions() {
     return this.get('_loadAvailableVersions').perform();
   },
 
-  currentVersion: computed('versions.[]', function() {
-    let versions = this.get('versions');
+  root: computed('currentVersion.path', function() {
+    let rootURL = getOwner(this).resolveRegistration('config:environment').rootURL;
+    return rootURL.replace(`/${this.get('currentVersion.path')}/`, '/');
+  }),
 
-    if (versions) {
-      return versions.find(version => version.name === this.get('current'));
+  currentVersion: computed(function() {
+    let config = getOwner(this).resolveRegistration('config:environment')['ember-cli-addon-docs'];
+    let currentVersion = config.deployVersion;
+
+    // In development, this token won't have been replaced replaced
+    if (currentVersion === 'ADDON_DOCS_DEPLOY_VERSION') {
+      currentVersion = {
+        name: 'latest',
+        tag: config.projectTag,
+        path: '',
+        sha: 'abcde'
+      };
     }
+
+    return currentVersion;
   })
 
 });

index.js

@@ -58,7 +58,8 @@ module.exports = {
       'ember-cli-addon-docs': {
         projectName: this.parent.pkg.name,
         projectTag: this.parent.pkg.version,
-        projectHref: info && info.browse()
+        projectHref: info && info.browse(),
+        deployVersion: 'ADDON_DOCS_DEPLOY_VERSION'
       }
     };
 

lib/config.js

@@ -1,13 +1,21 @@
 'use strict';
 
 const gitRepoInfo = require('git-repo-info');
+const hostedGitInfo = require('hosted-git-info');
 const semver = require('semver');
 
 module.exports = class AddonDocsConfig {
-  constructor() {
+  constructor(project) {
+    this.project = project;
     this.repoInfo = gitRepoInfo();
   }
 
+  getRootURL() {
+    let repository = this.project.pkg.repository || '';
+    let info = hostedGitInfo.fromUrl(repository.url || repository);
+    return info && info.project || this.project.name();
+  }
+
   getVersionPath() {
     if ('ADDON_DOCS_VERSION_PATH' in process.env) {
       return process.env.ADDON_DOCS_VERSION_PATH;

lib/deploy/plugin.js

@@ -38,12 +38,12 @@ module.exports = class AddonDocsDeployPlugin {
   }
 
   willUpload(context) {
-    let relativeBuildDestination = this.userConfig.getVersionPath();
+    let relativeBuildDestination = this._getVersionPath();
     let stagingDirectory = context.addonDocs.stagingDirectory;
     let fullBuildDestination = path.join(stagingDirectory, relativeBuildDestination);
 
     return this._copyExistingFiles(context, relativeBuildDestination)
-      .then(() => this._copyBuildOutput(context, fullBuildDestination))
+      .then(() => this._copyBuildOutput(context, stagingDirectory, relativeBuildDestination))
       .then(() => this._verifyRootFiles(stagingDirectory))
       .then(() => this._updateVersionsManifest(stagingDirectory))
       .then(() => this._maybeUpdateLatest(context, stagingDirectory, fullBuildDestination))
@@ -54,27 +54,36 @@ module.exports = class AddonDocsDeployPlugin {
     quickTemp.remove(this, 'deployStagingDirectory');
   }
 
+  _getVersionPath(version) {
+    return version || this.userConfig.getVersionPath();
+  }
+
   _verifyRootFiles(stagingDirectory) {
     let vendorDir = `${__dirname}/../../vendor/ember-cli-addon-docs`;
 
-    for (let file of ['index.html', '404.html']) {
-      if (!fs.existsSync(`${stagingDirectory}/${file}`)) {
-        fs.copySync(`${vendorDir}/${file}`, `${stagingDirectory}/${file}`);
-      }
+    if (!fs.existsSync(`${stagingDirectory}/index.html`)) {
+      fs.copySync(`${vendorDir}/index.html`, `${stagingDirectory}/index.html`);
     }
+
+    let segmentCount = this._getRootURL().split('/').length + 1;
+    let redirectContents = fs.readFileSync(`${vendorDir}/404.html`, 'utf-8');
+    redirectContents = redirectContents.replace(/\bADDON_DOCS_SEGMENT_COUNT\b/g, segmentCount);
+    fs.writeFileSync(`${stagingDirectory}/404.html`, redirectContents);
+  }
+
+  _getRootURL() {
+    return this.userConfig.getRootURL().replace(/^\/|\/$/g, '');
   }
 
   _updateVersionsManifest(stagingDirectory) {
     let versionsFile = `${stagingDirectory}/versions.json`;
     let versions = fs.existsSync(versionsFile) ? fs.readJSONSync(versionsFile) : {};
-    let path = this.userConfig.getVersionPath();
-    let name = this.userConfig.getVersionName();
-    let sha = this.userConfig.repoInfo.sha;
-    let tag = this.userConfig.repoInfo.tag;
+    let version = this._currentDeployVersion();
+
+    versions[version.name] = version;
 
-    versions[path] = { sha, tag, path, name };
     if (this.userConfig.shouldUpdateLatest()) {
-      versions['latest'] = { sha, tag, path: 'latest', name: 'latest' };
+      versions['latest'] = this._latestDeployVersion();
     }
 
     fs.writeJSONSync(versionsFile, versions, { spaces: 2 });
@@ -94,32 +103,49 @@ module.exports = class AddonDocsDeployPlugin {
     return fs.copy(from, to, { filter });
   }
 
-  _copyBuildOutput(context, fullBuildDestination) {
+  _copyBuildOutput(context, stagingDirectory, relativeBuildDestination) {
+    let fullBuildDestination = `${stagingDirectory}/${relativeBuildDestination}`;
+    let deployVersion = this._currentDeployVersion();
     return fs.copy(context.distDir, fullBuildDestination, { overwrite: true })
-      .then(() => this._updateRootURL(context, fullBuildDestination));
+      .then(() => this._updateIndexContents(context, stagingDirectory, relativeBuildDestination, deployVersion));
   }
 
   _maybeUpdateLatest(context, stagingDirectory) {
     if (!this.userConfig.shouldUpdateLatest()) { return; }
 
-    let latestDir = path.join(stagingDirectory, 'latest');
-    return fs.remove(latestDir)
-      .then(() => fs.copy(context.distDir, latestDir))
-      .then(() => this._updateRootURL(context, latestDir));
+    let latestDir = this._getVersionPath('latest');
+    let fullPath = path.join(stagingDirectory, latestDir);
+    let deployVersion = this._latestDeployVersion();
+    return fs.remove(fullPath)
+      .then(() => fs.copy(context.distDir, fullPath))
+      .then(() => this._updateIndexContents(context, stagingDirectory, latestDir, deployVersion));
   }
 
-  _updateRootURL(context, appRoot) {
-    let indexPath = `${appRoot}/index.html`;
-    let rootURL = `${this._projectName(context)}/${path.basename(appRoot)}`;
+  _updateIndexContents(context, stagingDirectory, appRoot, deployVersion) {
+    let indexPath = `${stagingDirectory}/${appRoot}/index.html`;
+    let rootURL = [this._getRootURL(), appRoot].filter(Boolean).join('/');
     let contents = fs.readFileSync(indexPath, 'utf-8');
-    let updated = contents.replace(/\bADDON_DOCS_ROOT_URL\b/g, rootURL);
+    let encodedVersion = encodeURIComponent(JSON.stringify(deployVersion));
+    let updated = contents.replace(/\/?ADDON_DOCS_ROOT_URL\/?/g, `/${rootURL}/`)
+      .replace(/%22ADDON_DOCS_DEPLOY_VERSION%22/g, encodedVersion);
+
     fs.writeFileSync(indexPath, updated);
   }
 
-  _projectName(context) {
-    let repository = context.config.git.repo;
-    let info = hostedGitInfo.fromUrl(repository);
-    return info && info.project || context.project.name();
+  _currentDeployVersion() {
+    let path = this._getVersionPath();
+    let name = this.userConfig.getVersionName();
+    let sha = this.userConfig.repoInfo.sha;
+    let tag = this.userConfig.repoInfo.tag;
+    return { path, name, sha, tag };
+  }
+
+  _latestDeployVersion() {
+    let path = this._getVersionPath('latest');
+    let name = 'latest';
+    let sha = this.userConfig.repoInfo.sha;
+    let tag = this.userConfig.repoInfo.tag;
+    return { path, name, sha, tag };
   }
 
   _inferRepoUrl(context) {

lib/utils/read-config.js

@@ -14,5 +14,5 @@ module.exports = function readConfig(project) {
     }
   }
 
-  return new ConfigClass();
+  return new ConfigClass(project);
 }

tests/acceptance/version-selector-test.js

@@ -8,13 +8,11 @@ module('Acceptance | Version selector test', function(hooks) {
   setupMirage(hooks);
 
   test('if the current version is latest and latest has a tag, it displays the tag', async function(assert) {
-    server.get('/versions.json', {
-      "latest": {
-        "sha": "53b73465d31925f26fd1f77881aefcaccce2915a",
-        "tag": 'v0.1.0',
-        "path": "latest",
-        "name": "latest"
-      },
+    this.owner.lookup('service:project-version').set('currentVersion', {
+      "sha": "53b73465d31925f26fd1f77881aefcaccce2915a",
+      "tag": 'v0.1.0',
+      "path": "latest",
+      "name": "latest"
     });
 
     await visit('/');
@@ -23,13 +21,11 @@ module('Acceptance | Version selector test', function(hooks) {
   });
 
   test(`if the current version is latest and latest doesn't have a tag, it displays Latest`, async function(assert) {
-    server.get('/versions.json', {
-      "latest": {
-        "sha": "53b73465d31925f26fd1f77881aefcaccce2915a",
-        "tag": null,
-        "path": "latest",
-        "name": "latest"
-      },
+    this.owner.lookup('service:project-version').set('currentVersion', {
+      "sha": "53b73465d31925f26fd1f77881aefcaccce2915a",
+      "tag": null,
+      "path": "latest",
+      "name": "latest"
     });
 
     await visit('/');

tests/dummy/app/pods/docs/deploying/template.md

@@ -141,6 +141,14 @@ This method returns a name for a given version of your documentation. By default
 
 This method determines whether the `/latest` directory will also be updated with the current deploy. By default, this will return true for builds from a tagged commit where the tag is a [semver non-prerelease version]([node-semver](https://github.com/npm/node-semver), and false otherwise. You can explicitly set the `ADDON_DOCS_UPDATE_LATEST` environment variable to `true` or `false` to override this behavior.
 
+### `getRootURL()`
+
+This method determines the static path under which all deploys of your docs app expect to live. It defaults to the name of your project, which matches the typical GitHub Pages setup where your site lives at <u>https://**[user]**.github.io/**[project]**/...</u>.
+
+If instead, however, you want to [set up a CNAME for your project](https://help.github.com/articles/using-a-custom-domain-with-github-pages/) and host it at e.g. <u>https://my-great-project.com</u>, you would override this method to return `''`, since there would be no static path at the beginning of the URL.
+
+**Note**: if you change this configuration after you've already deployed copies of your docs site, you'll need to check out your `gh-pages` branch and find/replace your previous root URL in those copies in order for them to continue to function in their new location.
+
 ## Removing a Deployed Version
 
 Deploying a version of your documentation does two things: it copies the `dist` directory of your built docs app into a particular place on your `gh-pages` branch, and it adds or updates an entry in the `versions.json` manifest in the root of that branch. To remove a version, then, you just need to undo those two things.

vendor/ember-cli-addon-docs/404.html

@@ -22,7 +22,7 @@
       // https://username.github.io/repo-name/one/two?a=b&c=d#qwe becomes
       // https://username.github.io/repo-name/?p=/one/two&q=a=b~and~c=d#qwe
       // Otherwise, leave segmentCount as 0.
-      var segmentCount = 2;
+      var segmentCount = ADDON_DOCS_SEGMENT_COUNT;
       var l = window.location;
       var segments = l.pathname.split('/');
 
@@ -38,5 +38,5 @@
       }
     </script>
   </head>
-  <body>The request page wasn't found.</body>
+  <body>The requested page wasn't found.</body>
 </html>