[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

@@ -9,20 +9,23 @@
 ### Overview
 
 An overview of MarkBind's Command Line Interface (CLI) can be referenced with `markbind --help`:
-```
+
+```bash
 $ markbind --help
 Usage: markbind <command>
 
  Options:
-   -V, --version                      output the version number
-   -h, --help                         output usage information
+   -V, --version                                      output the version number
+   -h, --help                                         output usage information
 
  Commands:
-   init|i [options] [root]            init a markbind website project
-   serve|s [options] [root]           build then serve a website from a directory
-   build|b [options] [root] [output]  build a website
-   deploy|d [options]                 deploy the site to the repo's GitHub pages
+   init|i [options] [root]                            init a markbind website project
+   serve|s [options] [root]                           build then serve a website from a directory
+   build|b [options] [root] [output]                  build a website
+   archive|ar [options] [versionName] [archivePath]   archive the current version of the site
+   deploy|d [options]                                 deploy the site to the repo's GitHub pages
 ```
+
 <hr><!-- ========================================================================== -->
 <div id="markbind-init">
 
@@ -116,13 +119,16 @@ The caveat is that not building all pages during the initial process, or not reb
    Force live reload to process all files in the site, instead of just the relevant files. This option is useful when you are modifying a file that is not a file type monitored by the <trigger trigger="click" for="modal:cliCommands-livePreview">live preview</trigger> feature.
 
 * `-p <port>`, `--port <port>`<br>
-    Serve the website in the specified port.
+  Serve the website in the specified port.
 
+* `-v [versionNames...]`, `--versions [versionNames...]` <br>
+  Specify version names to be deployed, separated by spaces. If the flag is used without specification, deploy all versions saved.
 
 {{ icon_examples }}
 * `markbind serve`
 * `markbind serve ./myWebsite`
 * `markbind serve -p 8888 -s otherSite.json`
+* `markbind serve -n -v` : Serve the site without opening a live preview in the browser, with all saved versions deployed
 
 </panel>
 
@@ -158,10 +164,63 @@ The caveat is that not building all pages during the initial process, or not reb
   Specify the site config file (default: `site.json`)<br>
   {{ icon_example }} `-s otherSite.json`
 
+* `-v [versionNames...]`, `--versions [versionNames...]` <br>
+  Specify version names to be deployed, separated by spaces. If the flag is used without specification, deploy all versions saved.
+
 **{{ icon_examples }}**
 * `markbind build`
 * `markbind build ./myWebsite ./myOutDir`
 * `markbind build ./stagingDir --baseUrl staging`
+* `markbind build -v v2.1.1` : Build the site and also deploy the version named 'v2.1.1'
+
+</panel>
+
+<hr><!-- ========================================================================== -->
+
+### `archive` Command
+<br>
+
+**Format:** `markbind archive [options] [versionName] [archivePath]`
+
+**Alias:** `markbind ar`
+
+**Description:** Does the following steps:
+
+1. Builds the current site, ignoring previously archived versions.
+1. Updates or creates a `versions.json` file to track the newly archived version.
+1. Puts the generated files in a folder of the specified name in the specified place.
+
+**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 }} `v1`, `v1.1.1`, `sem1-2022`
+
+* `[archivePath]`<br>
+  All archived versions are stored in the folder `<archivePath>`. The default archivePath is `version/${versionName}` <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`
+* `markbind archive version_1 custom_archive_path`: Stores the site in the directory `./custom_archive_path`
+
+%%{{ icon_info }} Related: [User Guide: Site Versioning](versioning.md).%%
 
 </panel>
 
@@ -200,5 +259,6 @@ The caveat is that not building all pages during the initial process, or not reb
 **Description:** Prints a summary of MarkBind commands or a detailed usage guide for the given `command`.
 
 {{ icon_examples }}
+
 * `markbind --help` : Prints a summary of MarkBind commands.
 * `markbind serve --help` : Prints a detailed usage guide for the `serve` command.

docs/userGuide/deployingTheSite.md

@@ -538,4 +538,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/siteJsonFile.md

@@ -72,7 +72,8 @@ Here is a typical `site.json` file:
   "headingIndexingLevel": 4,
   "intrasiteLinkValidation": {
     "enabled": false
-  }
+  },
+  "versions" : ["v1"]
 }
 ```
 
@@ -268,3 +269,9 @@ To disable this validation **entirely**, you may add the following to `site.json
   ```
 
 </div>
+
+#### **`versions`**
+
+**A list of version names to deploy by default when building and serving the site**. If this list is not present, by default no versions will be deployed. (You can override these settings by passing the `--versions` flag to build and serve -- see the [MarkBind CLI page](cliCommands.md) for more.)
+
+The version names to specify should be the same ones as in `versions.json`. Refer to the [Site Versioning](versioning.md) for more details.

docs/userGuide/versioning.md

@@ -0,0 +1,78 @@
+{% 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](cliCommands.md#archive-command). All intralinks within the archived site will point to the respective archived pages. By default, the archived site is stored in a folder `version/<versionName>`, but you may specify your own archivePath.
+
+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 can 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. This file is **automatically updated** every time you archive a version.
+
+<box type="warning">
+
+Modify versions.json with caution as it may result in unnecessary files being included or necessary files being excluded.
+
+* You may safely change the `versionName` of a version, **provided that it is unique** in versions.json. If you have specified versions to deploy in `site.json`, make sure you update the [versions property](siteJsonFile.md#versions) there as well.
+
+* The baseUrl is used when setting the intra-site links; if you later change the baseUrl, previously saved versions with the past baseUrl will not be built/deployed even if specified because it would be a broken implementation.
+
+</box>
+
+```json {heading="Example of a versions.json file"}
+{
+  "versions": [
+    {
+      "versionName": "v1",
+      "buildVer": "3.1.1",
+      "archivePath": "version/v1",
+      "baseUrl": "/previousUrl"
+    },
+    {
+      "versionName": "v2",
+      "buildVer": "3.1.1",
+      "archivePath": "version/v2",
+      "baseUrl": "/markbind"
+    },
+    {
+      "versionName": "v3",
+      "buildVer": "3.1.1",
+      "archivePath": "version/v3",
+      "baseUrl": "/markbind"
+    }
+  ]
+}
+
+```
+
+<include src="cliCommands.md#archiveWarning" />
+
+## Working with sites with multiple versions
+
+You may not always want to build all your saved versions. To specify the "default versions to build", add a [versions property](siteJsonFile.md#versions) in your `site.json` file.
+
+You may also specify which versions to build when using the build and serve cli commands([more information](cliCommands.md)).
+
+## Note on subsites
+
+At present, when a site is archived and includes a subsite, it archives the subsite as it was at that point in time. Navigating to previous or future versions of the subsite from the parent site is not supported, though you can archive the subsite.
+
+{% from "njk/common.njk" import previous_next %}
+{{ previous_next('deployingTheSite', 'markBindInTheProjectWorkflow') }}

packages/cli/index.js

@@ -98,6 +98,8 @@ program
   .option('-p, --port <port>', 'port for server to listen on (Default is 8080)')
   .option('-s, --site-config <file>', 'specify the site config file (default: site.json)')
   .option('-d, --dev', 'development mode, enabling live & hot reload for frontend source files.')
+  .option('-v, --versions [versionNames...]',
+          'specify versions to be deployed. if flag is used without specification, deploy all versions')
   .action((userSpecifiedRoot, options) => {
     if (options.dev) {
       logger.useDebugConsole();
@@ -262,7 +264,7 @@ program
           serverConfig.open = serverConfig.open && `${config.baseUrl}/`;
         }
 
-        return site.generate();
+        return site.generate(undefined, options.versions);
       })
       .then(() => {
         const watcher = chokidar.watch(rootFolder, {
@@ -298,6 +300,8 @@ program
   .option('--baseUrl [baseUrl]',
           'optional flag which overrides baseUrl in site.json, leave argument empty for empty baseUrl')
   .option('-s, --site-config <file>', 'specify the site config file (default: site.json)')
+  .option('-v, --versions [versionNames...]',
+          'specify versions to be deployed. if flag is used without specification, deploy all versions')
   .description('build a website')
   .action((userSpecifiedRoot, output, options) => {
     // if --baseUrl contains no arguments (options.baseUrl === true) then set baseUrl to empty string
@@ -311,13 +315,33 @@ program
     const defaultOutputRoot = path.join(rootFolder, '_site');
     const outputFolder = output ? path.resolve(process.cwd(), output) : defaultOutputRoot;
     new Site(rootFolder, outputFolder, undefined, undefined, options.siteConfig)
-      .generate(baseUrl)
+      .generate(baseUrl, options.versions)
       .then(() => {
         logger.info('Build success!');
       })
       .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/${versionName}`;
+    const rootFolder = path.resolve(process.cwd());
+    const outputFolder = path.join(rootFolder, archivePath);
+    new Site(rootFolder, outputFolder, undefined, undefined, options.siteConfig)
+      .archive(versionName, archivePath)
+      .then(() => {
+        logger.info(`Successfully archived ${versionName} at ${archivePath}`);
+      })
+      .catch(handleError);
+  });
+
 program
   .command('deploy')
   .alias('d')
@@ -327,7 +351,8 @@ program
   .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)
+    new Site(rootFolder, outputRoot, undefined, undefined, options.siteConfig)
+      .deploy(options.ci)
       .then(depUrl => (depUrl !== null ? logger.info(
         `The website has been deployed at: ${depUrl}`)
         : logger.info('Deployed!')))

packages/core/src/Site/SiteConfig.js

@@ -105,6 +105,11 @@ class SiteConfig {
      */
     this.intrasiteLinkValidation = siteConfigJson.intrasiteLinkValidation || {};
     this.intrasiteLinkValidation.enabled = this.intrasiteLinkValidation.enabled !== false;
+
+    /**
+     * @type {Array}
+     */
+    this.versions = siteConfigJson.versions || [];
   }
 }
 

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,