Build Instructions
Generating the Static HTML Site
Files within the structure above can either be viewed on a local development server (generally to test the functionality of the site) or built to HTML and javascript files that can be uploaded and served from a webhost. One of the benefits of Static HTML is that there is no database component, so the files can be sent via FTP to a hosting service and the site just works. Alternaively, and this is something we still need to test, static html files can be added to a Sharepoint site, and then can be accessed by viewing the index.aspx file. Sharepoint will serve the html directly, with no additional hosting required. Details
After cloning the repository, you need to run yarn install to create the additional files needed by Docusaurus to function. They’re the ones found in .gitignore in the repository. Yarn 4 is different from prior verions of Yarn and as of 11/2023 is installed after node.js with corepack enable.
Prior to building the site don't forget to update the Docs Version numbers in the docusaurus.config.js and package.json files.
Each of the commands below should be run from within the project directory.
Installation
cd project-folder
yarn install
This command generates the files needed for Docusaurus to create both the development server an the build directory.
Local Development
cd project-folder
yarn start
This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.
Build
cd project-folder
yarn build
This command generates static content into the build directory and can be served using any static contents hosting service.
Password Protection
So maaaaaybe there's a little issue with who actually owns the copyright to the source files used to generate this documentation. While it's under active development, we probably want to keep access restricted to just a handful of people. I went for the laziest possible option and simply encrypted the index page of the built site so that it requires a password to enter. Note that this is the only page that is encrypted right now. If you send someone any link other than the main index it's fully free and available out on the internet. If at a later point we determine we want to encrypt all of it, that is certainly possible, I just don't think it's worth the effort for our proof of concept.
index.html is encrypted with a tool called staticrypt. This has just been manually run on that file after the build process, and then the index_encrypted.html replaces index.html on the live site (renamed to index.html of course).