Development

This page describes how the site itself works, for those who want to add or change functionality. Note most of the time this is not necessary! Github has a nice editor for Markdown, and PRs that are merged will be automatically deployed. This guide is for more complicated changes that require local testing before deployment.

The site itself is hosted via Google Firebase. This allows us to created restricted-access portions of the site, which will require a Broad login.

Local development

You can create a local copy of this site by cloning the GitHub repo. It is probably best to create an environment for this, and then install the following requirements (there might be more, edit this page if necessary!):

conda install python mkdocs nodejs=14
npm install -g firebase-tools  # install the firebase CLI

Once the requirements are installed you should be able to view a local copy of the website using mkdocs serve. This can be useful if you are writing up a complicated addition to the wiki and want to preview your changes and test the links before deploying.

Using Firebase

Another way to run a local server is with firebase serve. This works slightly differently: mkdocs serve serves the files from src/, while firebase serve serves the compiled HTML from public/. So, first you need to build the site with mkdocs build. This will also allow the cloud function to work, if you need to verify the internal pages are protected. To do that, you need to remove the internal files from the public directory with rm -r public/internal.

Advanced: Deploying to Firebase

Most of the time, we should not need to deploy the site from the command-line. There is a Github Action set up in the repo that will deploy the site upon any commit to the main branch, including merged PRs. However, the action does not update the Cloud Function that is reponsible for serving protected content (anything under /internal/)—the content can be updated, but changes to the code itself need to be deployed. To do that, we need to use the Firebase CLI. However, this requires a couple extra steps (potentially these could be automated in the future):

  1. Build the site with mkdocs build
  2. Copy the internal pages to Google storage: gsutil rsync -r public/internal gs://macosko-lab-wiki/internal
  3. Remove the internal pages from the public directory: rm -r public/internal
  4. Update the site and functions with firebase deploy

If the internal directory is not removed before the deploy, those pages will be public. So it's important to remember these steps!