[Request for comments]: Site Versioning

docs/_markbind/layouts/userGuide.md

@@ -30,6 +30,7 @@
   * [Making the Site Searchable]({{baseUrl}}/userGuide/makingTheSiteSearchable.html)
   * [Applying Themes]({{baseUrl}}/userGuide/themes.html)
   * [Deploying the Site]({{baseUrl}}/userGuide/deployingTheSite.html)
+  * [Versioning]({{baseUrl}}/userGuide/versioning.html)
   * [MarkBind in the Project Workflow]({{baseUrl}}/userGuide/markBindInTheProjectWorkflow.html)
 * **References** :expanded:
   * [CLI Commands]({{baseUrl}}/userGuide/cliCommands.html)

docs/userGuide/cliCommands.md

@@ -167,6 +167,48 @@ The caveat is that not building all pages during the initial process, or not reb
 
 <hr><!-- ========================================================================== -->
 
+### `archive` Command
+<br>
+
+**Format:** `markbind archive [options] [versionName] [archivePath]`
+
+**Alias:** `markbind ar`
+
+**Description:** Archives a version of the current site, which will not be affected by future changes to the site
+
+**Arguments:**
+
+<div id="archiveWarning">
+<box type="warning">
+
+Warning: If the folder at `<archivePath>/<versionName>` already exists, the contents will be overwritten and your previous files may be lost. Only do so if you need to replace all the archived files with the current site files.
+</box>
+</div>
+
+* `[versionName]`<br>
+  The name of the version, and the folder which the generated HTML files and assets will be stored in.<br>
+  {{ icon_example }} `version_1`
+
+* `[archivePath]`<br>
+  All archived versions are stored in the folder `<archivePath>/<versionName>`. The default archivePath is `version` <br>
+  {{ icon_example }} `custom_archive_path`
+
+<panel header="**Options** :fas-cogs:" type="minimal" expanded>
+
+**Options** :fas-cogs:
+
+* `-s <file>`, `--site-config <file>`<br>
+  Specify the site config file (default: `site.json`)<br>
+  {{ icon_example }} `-s otherSite.json`
+
+**{{ icon_examples }}**
+* `markbind archive v1` - Stores the site in the directory `version/v1` (from the root)
+* `markbind archive version_1 custom_archive_path` - Stores the site in the directory `custom_archive_path/version_1` (from the root)
+
+</panel>
+
+<hr><!-- ========================================================================== -->
+
 ### `deploy` Command
 <br>
 

docs/userGuide/deployingTheSite.md

@@ -517,4 +517,4 @@ For more information on Surge, you may refer to [Surge's docs](https://surge.sh/
 </panel>
 
 {% from "njk/common.njk" import previous_next %}
-{{ previous_next('themes', 'markBindInTheProjectWorkflow') }}
+{{ previous_next('themes', 'versioning') }}

docs/userGuide/markBindInTheProjectWorkflow.md

@@ -66,4 +66,4 @@ To convert your existing project, follow these steps:
 </box> 
 
 {% from "njk/common.njk" import previous_next %}
-{{ previous_next('deployingTheSite', '') }}
+{{ previous_next('versioning', '') }}

docs/userGuide/versioning.md

@@ -0,0 +1,32 @@
+{% set title = "Site Versioning" %}
+{% set filename = "versioning" %}
+<span id="title" class="d-none">{{ title }}</span>
+
+<frontmatter>
+  title: "User Guide: {{ title }}"
+  layout: userGuide.md
+</frontmatter>
+
+<span id="link" class="d-none">
+<md>[_User Guide → {{ title }}_]({{ filename }}.html)</md>
+</span>
+
+# {{ title }}
+
+<div class="lead" id="overview">
+
+Site versioning is key for documentation use, and websites may want to keep past versions for archival purposes. MarkBind can help you easily archive your site.
+</div>
+
+## Archiving with a CLI command
+
+Markbind allows you to easily save a version of the site you've built to be hosted at the same site with a modified URL with a single CLI command. All intralinks within the archived site will point to the respective archived pages. By default, the archive folder is called `version`, but you may specify your own directory.
+
+For example, if your site's base url relative to your domain is 'my_site', and you archive a version named 'v1' in the default archive folder, then by navigating to the url `<domain>/my_site/version/v1/<someFile>` you would have accessed the archived version of someFile.
+
+A `versions.json` file will be created to track the archived sites you have made, and to exclude the archived sites from being re-archived the next time you make a new version. Modify it with caution, as it may result in unnecessary files being included or necessary files being excluded.
+
+<include src="cliCommands.md#archiveWarning">
+
+{% from "njk/common.njk" import previous_next %}
+{{ previous_next('deployingTheSite', 'markBindInTheProjectWorkflow') }}

packages/cli/index.js

@@ -318,16 +318,38 @@ program
       .catch(handleError);
   });
 
+program
+  .command('archive [versionName] [archivePath]')
+  .alias('ar')
+  .option('-s, --site-config <file>', 'specify the site config file (default: site.json)')
+  .description('archive a version of the site, which is not affected by later changes to the site')
+  .action((versionName, userSpecifiedArchivePath, options) => {
+    if (!versionName) {
+      logger.error('Please specify a name for the archived version.');
+    }
+    const archivePath = userSpecifiedArchivePath || 'version';
+    const rootFolder = path.resolve(process.cwd());
+    const outputFolder = path.join(rootFolder, archivePath, versionName);
+    new Site(rootFolder, outputFolder, undefined, undefined, options.siteConfig)
+      .archive(versionName, archivePath)
+      .then(() => {
+        logger.info(`Successfully archived ${versionName} at ${archivePath}/${versionName}`);
+      })
+      .catch(handleError);
+  });
+
 program
   .command('deploy')
   .alias('d')
   .description('deploy the site to the repo\'s Github pages')
   .option('-c, --ci [githubTokenName]', 'deploy the site in CI Environment [GITHUB_TOKEN]')
   .option('-s, --site-config <file>', 'specify the site config file (default: site.json)')
+  .option('-v, --versions <versionFolder>', 'specify the path where versions are stored')
   .action((options) => {
     const rootFolder = path.resolve(process.cwd());
     const outputRoot = path.join(rootFolder, '_site');
-    new Site(rootFolder, outputRoot, undefined, undefined, options.siteConfig).deploy(options.ci)
+    const site = new Site(rootFolder, outputRoot, undefined, undefined, options.siteConfig);
+    site.deploy(options.ci)
       .then(depUrl => (depUrl !== null ? logger.info(
         `The website has been deployed at: ${depUrl}`)
         : logger.info('Deployed!')))

packages/core/src/Site/constants.js

@@ -12,6 +12,7 @@ module.exports = {
   PAGE_TEMPLATE_NAME: 'page.njk',
   SITE_CONFIG_NAME: 'site.json',
   SITE_DATA_NAME: 'siteData.json',
+  VERSIONS_DATA_NAME: 'versions.json',
   LAYOUT_SITE_FOLDER_NAME: 'layouts',
   LAZY_LOADING_SITE_FILE_NAME: 'LazyLiveReloadLoadingSite.html',
   LAZY_LOADING_BUILD_TIME_RECOMMENDATION_LIMIT: 30000,

packages/core/src/Site/index.js

@@ -64,6 +64,7 @@ const {
   PAGE_TEMPLATE_NAME,
   SITE_CONFIG_NAME,
   SITE_DATA_NAME,
+  VERSIONS_DATA_NAME,
   SITE_FOLDER_NAME,
   TEMP_FOLDER_NAME,
   TEMPLATE_SITE_ASSET_FOLDER_NAME,
@@ -134,6 +135,12 @@ class Site {
     this.siteConfig = undefined;
     this.siteConfigPath = siteConfigPath;
 
+    /**
+     * Archived version information
+     * @type {undefined | SiteConfig}
+     */
+    this.versionData = undefined;
+
     // Site wide variable processor
     this.variableProcessor = undefined;
 
@@ -652,17 +659,8 @@ class Site {
 
     try {
       await this.readSiteConfig(baseUrl);
-      this.collectAddressablePages();
-      await this.collectBaseUrl();
-      this.collectUserDefinedVariablesMap();
-      await this.buildAssets();
-      await (this.onePagePath ? this.lazyBuildSourceFiles() : this.buildSourceFiles());
-      await this.copyCoreWebAsset();
-      await this.copyBootstrapTheme(false);
-      await this.copyFontAwesomeAsset();
-      await this.copyOcticonsAsset();
-      await this.copyMaterialIconsAsset();
-      await this.writeSiteData();
+      await this.buildSiteHelper();
+
       this.calculateBuildTimeForGenerate(startTime, lazyWebsiteGenerationString);
       if (this.backgroundBuildMode) {
         this.backgroundBuildNotViewedFiles();
@@ -672,6 +670,23 @@ class Site {
     }
   }
 
+  /**
+   * Holds the work for generating a site.
+   */
+  async buildSiteHelper() {
+    this.collectAddressablePages();
+    await this.collectBaseUrl();
+    this.collectUserDefinedVariablesMap();
+    await this.buildAssets();
+    await (this.onePagePath ? this.lazyBuildSourceFiles() : this.buildSourceFiles());
+    await this.copyCoreWebAsset();
+    await this.copyBootstrapTheme(false);
+    await this.copyFontAwesomeAsset();
+    await this.copyOcticonsAsset();
+    await this.copyMaterialIconsAsset();
+    await this.writeSiteData();
+  }
+
   /**
    * Helper function for generate().
    */
@@ -1467,6 +1482,84 @@ class Site {
     }
   }
 
+  /**
+   * Archive the current version of the site.
+   *
+   * @param {string} versionName the name of the version
+   * @param {string} archivePath the path to the folder to store the archives in
+   */
+  async archive(versionName, archivePath) {
+    await this.readSiteConfig();
+
+    // Save version data
+    const versionPath = `${archivePath}/${versionName}`;
+    this.versionData = await this.writeVersionsFile(versionName, versionPath);
+    // Exclude versioned files from archiving.
+    const archiveFolders = this.versionData.versions;
+    archiveFolders.forEach((folder) => {
+      const filePath = `/${folder.output}/**`;
+      this.siteConfig.ignore.push(filePath);
+    });
+
+    // Used to get accurate intralinks within the archived site:
+    const archivedBaseUrl = this.siteConfig.baseUrl === ''
+      ? `/${versionPath}`
+      : `${this.siteConfig.baseUrl}/${versionPath}`;
+    this.siteConfig.baseUrl = archivedBaseUrl;
+
+    // Create the .tmp folder for storing intermediate results.
+    fs.emptydirSync(this.tempPath);
+    // Clean the output folder; create it if not exist.
+    fs.emptydirSync(this.outputPath);
+
+    try {
+      await this.buildSiteHelper();
+    } catch (error) {
+      await Site.rejectHandler(error, [this.tempPath, this.outputPath]);
+    }
+  }
+
+  /**
+   * If the versions.json file exists, update it with a new version.
+   * Otherwise, create a new versions file to store information about archived versions
+   *
+   * @param {boolean} verbose Flag to emit logs of the operation
+   * @returns Returns the json object of the current versions data.
+   */
+  async writeVersionsFile(versionName, versionPath, verbose = true) {
+    const versionsPath = path.join(this.rootPath, VERSIONS_DATA_NAME);
+    const newVersionData = {
+      version_name: versionName,
+      build_ver: MARKBIND_VERSION,
+      output: versionPath,
+    };
+
+    try {
+      if (!fs.pathExistsSync(versionsPath)) {
+        // Initialize the versions.json file.
+        fs.outputJSONSync(versionsPath, { versions: [] }, { spaces: 2 });
+      }
+      const versionsJson = fs.readJSONSync(versionsPath);
+
+      // Add in or update this new version in the versions file.
+      const idx = versionsJson.versions.findIndex(vers => vers.output === newVersionData.output);
+      if (idx === -1) {
+        versionsJson.versions.push(newVersionData);
+      } else {
+        versionsJson.versions[idx] = newVersionData;
+      }
+      fs.writeJsonSync(versionsPath, versionsJson, { spaces: 2 });
+      if (verbose) {
+        logger.info('versions.json file updated');
+      }
+
+      return versionsJson;
+    } catch (error) {
+      await Site.rejectHandler(error, [this.tempPath, this.outputPath]);
+      return null;
+    }
+  }
+
   deploy(ciTokenVar) {
     const defaultDeployConfig = {
       branch: 'gh-pages',