[Request for comments]: Site Versioning

[kaixin-hc]

What is the purpose of this pull request?
MVP for #1009

• Documentation update
• Bug fix
• Feature addition or enhancement
• Code maintenance
• Others, please explain:

Overview of changes:

• Add a command to archive a version under a given name. Archived versions are stored in HTML format, in a folder with the version name, which is inside the version folder(default name for the version folder is "version"). All links in the versioned site will link to other pages in the versioned site.

To summarize the current solution, what it does is build the website and place it into a folder within the repository for it to be versioned (default location is version/, but you can customise this). When the site is built, by default the build action copies the versioned site over into _site, and it is deployed. If the user decides to store versions in different folders, then the URL to the version will simply be different.

TODO:

• Amend the way that links have their baseUrl changed such that it works even if baseUrl != ''
• Need to test for performance. (only a small difference: on MarkBind its 1/4th of a second, from ~ 4.75s to 5s.
• Multiple versions -- saving a subsequent version should not keep the version folders
• Clean up code
• Add documentation
• Add tests (?) How to test.

Anything you'd like to highlight / discuss:

Benefits of the solution proposed in this PR

• Simple & customisable
• Since .html and asset files are kept, past changes in markbind version, assets used, etc will be no issue --> each version contains everything it needs to deploy as a site
• (Relatively) performant. I don't have proof of this yet, but I believe copying the files of html folders/asset folders should be a relatively small cost, as compared to generating from markbind files.

Potential Drawbacks

• The user does need to remember which folder they store their versions in, since they can change the name of the folder, etc.
• Additional manual(?) cost in implementing frontend components and creating backups of their versions in branches/repositories if they happen to use git (could be mitigated by future PRs targetting this)

Thoughts

• Is the site.json file copied over in the versioned files still being used? ETA: with further investigation, site.json is not copied over, a siteData.json is being created instead.

CAVEATS:

• If the baseURL is changed, the baseURL of the versioned site does not change.

Testing instructions:

• markbind archive <versionName> [versionFolderName] --> builds and saves the site in a given version and folder name.
• markbind archive <versionName> builds and saves the site with a given version name in a folder called version

Access the site by manually appending <versionFolderName>/<version name> after the baseURL in the deployed site.

Proposed commit message: (wrap lines at 72 characters)

Implement a basic versioning CLI command

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

Let's implement a markbind-cli command, markbind archive, to allow
users to easily version their website. When markbind build/serve is run,
all links within the versioned site will point to their versioned equivalent.

---

Checklist: ☑️

• Updated the documentation for feature additions and enhancements
• Added tests for bug fixes or features
• Linked all related issues
• No unrelated changes

---

Stretch goals/future improvements

• Additional CLI commands to support renaming, moving versions, and deleting versions, so that users do not ever need to modify versions.json manually.

• Support live preview updating when the versions property of site.json is changed.

• Editing of previous versions. My preferred solution is saving versions in separate branches, holding all files, except previously archived versions. Update the deployed files by navigating to a separate branch (and take advantage of git; like say if you fix a bug which affects all versions, you can cherrypick the commit over to the versioned branch). This will also support reverting to previous versions (working and deploying off of the versioned branch...?). caveat: this is dependent on git.

  • Further support updating gh-pages from a versioned branch to update past versions. I think this should be possible, as the ghpages extension supports an "add" which would not remove existing files. We could remove the existing "version" directory and import the files from the branch back into main/the current branch, from which you can deploy as normal.
  • Believe this solution can account for MarkBind versions changing over time, as the master only holds the HTML files of each versioned site. Might require building and deploying to be done using NPM to ensure appropriate version control

• Front end component to easily navigate between versioned branches? Personally leaning towards a bannet, like in the 3281 site(note: banner component does not exist), but a component in the footer with a default message that you can change (like the "generated by markbind" message) might be sufficiently versatile to work as a default implementation. We could also have an auto-generated dropdown component which users can place in their navbar as desired. Key difficulty: making it versatile and customisable for all types of sites while also working "out of the box", since websites don't need to follow any set format, this may be difficult.