[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 <versionName> [options]                 archive the current version of the site
+   deploy|d [options]                                 deploy the site to the repo's GitHub pages
 ```
+
 <hr><!-- ========================================================================== -->
 <div id="markbind-init">
 
@@ -36,6 +39,7 @@ Usage: markbind <command>
 **Description:** Initializes a directory into a MarkBind site by creating a skeleton structure for the website which includes a `index.md` and a `site.json`.
 
 **Arguments:**
+
 * `[root]`<br>
   Root directory. Default is the current directory.<br>
   {{ icon_example }} `./myWebsite`
@@ -51,6 +55,7 @@ Usage: markbind <command>
   When initialising MarkBind, change the template that you start with. See [templates](templates.html).
 
 {{ icon_examples }}
+
 * `markbind init` : Initializes the site in the current working directory.
 * `markbind init ./myWebsite` : Initializes the site in `./myWebsite` directory.
 * `markbind init --convert --template minimal`: Converts the GitHub wiki or `docs` folder in the current working directory into a minimal MarkBind website.
@@ -67,6 +72,7 @@ Usage: markbind <command>
 **Alias:** `markbind s`
 
 **Description:** Does the following steps:
+
 1. Builds the site and puts the generated files in a directory named `_site`.
 1. Starts a web server instance locally and makes the site available at `http://127.0.0.1:8080`.
 1. Opens a <trigger trigger="click" for="modal:cliCommands-livePreview">live preview</trigger> of the website.
@@ -76,6 +82,7 @@ Usage: markbind <command>
 </modal>
 
 **Arguments:**
+
 * `[root]`<br>
   Root directory. The default is the directory where this command was executed.<br>
   {{ icon_example }} `./myWebsite`
@@ -100,7 +107,7 @@ The caveat is that not building all pages during the initial process, or not reb
 * `-b`, `--background-build` **[BETA]**<br>
    If `--one-page` is specified, this mode enhances the single-page serve by building the pages that are not yet built
    or marked to be rebuilt in the background.
-   
+
    You can still edit the pages during the background build. When MarkBind detects changes to the source
    files, the background build will stop, rebuild the files affected, then resumes the background build with the
    remaining pages.
@@ -116,13 +123,17 @@ 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 versions to be served, separated by spaces. If the flag is used without specification, serve no versions. Using this option overrides the versions settings in [`site.json`](siteJsonFile.md).
 
 {{ icon_examples }}
+
 * `markbind serve`
 * `markbind serve ./myWebsite`
 * `markbind serve -p 8888 -s otherSite.json`
+* `markbind serve -n -v LTS 1.0` : Serve the site without opening a live preview in the browser, and also serve the archived version named "LTS" and "1.0".
 
 </panel>
 
@@ -138,6 +149,7 @@ The caveat is that not building all pages during the initial process, or not reb
 **Description:** Generates the site to the directory named `_site` in the current directory.
 
 **Arguments:**
+
 * `[output]`<br>
   Put the generated files in the specified directory<br>
   {{ icon_example }} `../myOutDir`
@@ -158,10 +170,65 @@ 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 versions to be kept in the generated site, separated by spaces. If the flag is used without specification, keep no versions. Using this option overrides the versions settings in [site.json](siteJsonFile.md).
+
 **{{ icon_examples }}**
+
 * `markbind build`
 * `markbind build ./myWebsite ./myOutDir`
 * `markbind build ./stagingDir --baseUrl staging`
+* `markbind build -v v2.1.1` : Build the site with the version named 'v2.1.1' in addition to the current version
+
+</panel>
+
+<hr><!-- ========================================================================== -->
+
+### `archive` Command
+<br>
+
+**Format:** `markbind archive <versionName> [options]`
+
+**Alias:** `markbind ar <versionName>`
+
+**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 the specified `archivePath` folder (By default, the archive path is "version/<versionName>")
+
+**Arguments:**
+
+* `<versionName>`<br>
+  The name of the version. This is required, and names must be unique; using the same name and archivePath will result in the previous archived files being overwritten.<br>
+  {{ icon_example }} `v1`, `v1.1.1`, `sem1-2022`
+
+<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`
+* `-ap <archivePath>`, `--archive-path <archivePath>`<br>
+  All archived versions are stored in the folder `<archivePath>`. If not specified, the archive path is `version/${versionName}` <br>
+  {{ icon_example }} `-ap custom_archive_path`
+
+<div id="archiveWarning">
+  <box type="warning">
+
+  Warning: If the folder at `<archivePath>` 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.
+
+  (Also note that you cannot save a version with the same name into a different archive path.)
+  </box>
+</div>
+
+**{{ icon_examples }}**
+
+* `markbind archive v1`: Stores the archived site in the directory `./version/v1` as the version named 'v1'
+* `markbind archive version_1 -ap custom_archive_path`: Stores the archived site in the directory `./custom_archive_path`, and the version is named 'version_1'.
+
+%%{{ icon_info }} Related: [User Guide: Site Versioning](versioning.md).%%
 
 </panel>
 
@@ -200,5 +267,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

@@ -545,4 +545,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/glossary.md

@@ -10,7 +10,7 @@
 **_Live preview_** is:
 - Regeneration of affected content upon any change to <tooltip content="`.md`, `.njk` files ... anything your content depends on!">source files</tooltip>, then reloading the updated site in the Browser.
 
-- Regeneration will also occur upon any modification to attributes in `site.json` with the exception of [`baseUrl`](siteJsonFile.md#baseurl).
+- Regeneration will also occur upon any modification to attributes in `site.json` with the exception of the [`baseUrl`](siteJsonFile.md#baseurl) and [`versions`](siteJsonFile.md#versions) attributes.
 
 - Copying <tooltip content="files that don't affect page generation (eg. images), but are used in the site">assets</tooltip> to the site output folder.
 

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

@@ -75,6 +75,7 @@ Here is a typical `site.json` file:
   "intrasiteLinkValidation": {
     "enabled": false
   },
+  "versions" : ["v1"]
   "plantumlCheck": true
 }
 ```
@@ -275,6 +276,17 @@ 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.
+
+  ```js
+  ...
+  "versions": ["v1.1.2"] // build/deploy just v1.1.2 by default
+  ...
+  ```
 #### **`plantumlCheck`**
 
 **Toggle whether to display a warning about PlantUML's prerequisite.** By default, MarkBind will check if you have Graphviz installed when you are using PlantUML diagrams.

docs/userGuide/versioning.md

@@ -0,0 +1,99 @@
+{% 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>
+
+## Quickstart
+
+If you wanted to archive your site for the first time, you might use the following command.
+
+  ```bash
+  $ markbind archive v1 // archive the current site with the name v1 into the folder version/v1
+  ```
+
+Make whatever changes you want to your site without affecting this saved version. Then, run:
+
+  ```bash
+  $ markbind serve -v v1 // serve the site as well as the archived version named v1
+  ```
+
+Your served site will open automatically. By adding version/v1 to the url in your browser (for example from http://127.0.0.1:8080 to http://127.0.0.1:8080/version/v1), you will view the archived version of your site. Intralinks in the versioned site will only lead to the versioned site links. 
+
+To deploy your site with your archived site:
+
+  ```bash
+  $ markbind build -v v1 // generate site with the archived version named v1
+  $ markbind deploy
+  ```
+
+You can save which versions to automatically be served/deployed in [site.json](siteJsonFile.md#versions).
+
+## More on archiving
+
+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 using 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`, then by navigating to the URL `<domain>/my_site/version/v1/<someFile>` you can access 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)).
+
+{% 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 no 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 no 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,31 @@ 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>')
+  .alias('ar')
+  .option('-s, --site-config <file>', 'specify the site config file (default: site.json)')
+  .option('-ap, --archive-path <path>', 'specify a custom path to archive the site at')
+  .description('archive a version of the site, which is not affected by later changes to the site')
+  .action((versionName, options) => {
+    const archivePath = options.archivePath || `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')

packages/cli/test/functional/test_site/_markbind/versions.json

@@ -0,0 +1,3 @@
+{
+  "versions": []
+}

packages/cli/test/functional/test_site_algolia_plugin/_markbind/versions.json

@@ -0,0 +1,3 @@
+{
+  "versions": []
+}

packages/cli/test/functional/test_site_special_tags/_markbind/versions.json

@@ -0,0 +1,3 @@
+{
+  "versions": []
+}