Support site versioning

[ang-zeyu]

Is your request related to a problem?

Site versioning is key for documentation use, and education websites may want to keep past versions for archival purposes as well.

Describe the solution you'd like

As discussed, we can support some form of markbind archive <version name> command that builds and archives the site in a say, '/archive' directory.

The links in here would then be accessed with ${baseUrl}/archive/<version name>/<old link>.

To add, perhaps to link it easily to the front end we can automatically insert a navigation dropdown versions in the sitenav ( or navbar ) through an option in site.json.

[damithc]

Along the same vein, it's nice if we can support PR previews in ${baseUrl}/pulls/<PR number>/<old link>
On a related note, if we can do all this using GitHub actions + gh-pages, we can shed our dependency on Travis and Netlify at the same time.

[ang-zeyu]

A more comprehensive list of requirements for anyone interested:

• readers should be able to navigate to newer version from older versions - hence a single source of truth for versions is needed for all versions. (e.g. a versions.json output metadata file at the output (_site) and source folder root)
• the data file structure / design used to store versioning information should be extensible, so we can add more versioning information in the future as needed without breaking past versions
• a simple frontend versioning component should be provided, that allows readers to navigate to any version from any version (can be done separately)
• a markbind archive "version name" command
• re-executing this command should replace the version with a newly built one (see note on baseUrl below), so users can change the baseUrl
• a markbind "delete-archive" "version name" command (can be done separately)

Additional notes:

• The baseUrl may change across versions, if so, this would break the ability for past versions to navigate to newer versions since the single metadata file location would have changed

[tlylt]

Saw a somewhat related project that might give some ideas/inspirations:
mike,- Manage multiple versions of your MkDocs-powered documentation via Git

• The gh-pages branch looks like this

[kaixin-hc]

I'll be taking a crack at this issue in the coming weeks!

Initial thoughts:

• We could implement this by having the archive command move all the files used to generate the current site into archive/<version_name>
  • All the files in archive can use a special layout file, which changes maybe the top level theming to make it clear which version it is. There also ought to be a way to change back to the latest version or change to other versions
  • When transferred into this archive, all the internal links need to link to the current version of the files and not the latest version. Perhaps within the <version_name> folder we can change the {{ base_url }} ? Otherwise, all internal links would need to be changed appropriately
• I don't think we need a single meta-data file to track current and later base_urls for this solution, as there would only be a single repository and branch. If the base_url changes later, the older versions will also have a changed base_url
  • I think this is okay as it is unlikely you would need a totally independent older version of a current website.

Some points from a verbal discussion with Prof

• Would we want to allow editing the past versions?
• Should we be saving versions as markdown files, or .html files?
• Would we need a feature to revert to a previous version (stretch goal)
• How will this work with sub-sites? (can consider for later)

One concern was that repository size would balloon quickly, as once the version is added it would be saved in .git even if it is later deleted.

A potential workaround would be saving each version in a separate branch, where the name is the version name. Then the deploy command would keep track of the commit hashes where each version was saved, and use that branches files to generate html files to place in gh-pages. To lessen the time for the build command, deploy could be made more intelligent so that versioned files are only replaced if the commit hash has been changed since the last time. An additional feature that would need to be implemented is some command to 'build past version files' in order to produce the past version files in the current local branch.

[jonahtanjz]

Here are some of my thoughts on this.

Would we want to allow editing the past versions?

I think it would be nice to support editing past versions as this would be useful for updating the documentation of past releases (e.g bug fixes).

Should we be saving versions as markdown files, or .html files?

If we were to allow editing of past versions, then I think saving the past versions as .md files will make more sense as it will be easier for the users to edit and be able to use MarkBind's syntax.

To lessen the time for the build command, deploy could be made more intelligent so that versioned files are only replaced if the commit hash has been changed since the last time. An additional feature that would need to be implemented is some command to 'build past version files' in order to produce the past version files in the current local branch.

This will be useful for editing and deploying of past versions.

[damithc]

This could be one possible approach:

What authors need to do to deploy a 'archived' version of a website,

1. create a branch to represent the version e.g., branch-v-1-2-0
2. add the branch name and a version name (e.g., v1.2.0) to the site.json, under a list of archivedVersions
3. run the build/deploy commands as usual --> the version v1.2.0 will be available in a drop-down versions of the deployed website

A possible implementation:

For each branch_name, version_name in the archivedVersions

1. check if archive/version_name exsits (if it exists, the version has been generated already in a previous build -- no need to generate again.
2. if it does not exist, switch to branch_name and generate the version of the website into archive/version_name folder
3. copy over the generated version of the website into a sub folder under the _sites folder for subsequent deployment

But the above is just speculation. There could be other better ways of doing this.