About this site
This documentation site is built with Docusaurus (chosen over MkDocs + Material for its first-class support of MDX, static notebook rendering via the build pipeline, and a deployable/versioned single-page app built with Node, which is already available in this repository's toolchain).
How tutorial content is mapped
The canonical sources live in this repository, next to their scripts and notebooks:
| Tutorial | Source folder |
|---|---|
| GPU Computing in Oceanography | gpu_computing_oceanography/ |
| Knowledge Graphs for Chemistry | knowledge_graphs_chemistry/docs/ |
| Cloud Seismology Analysis | cloud_analysis_seismology/ |
| Toy Data Portal for Hydrology | toy_data_portal_hydrology/ |
A small sync step (website/scripts/sync.mjs, run via npm run sync) copies
each tutorial's markdown guides into website/tutorials/<slug>/ and
converts every *.ipynb notebook into static markdown (code cells + text
outputs + rendered PNG output images). Each tutorial is its own Docusaurus
docs instance, so the left sidebar shows only that tutorial's tree; the Home
sidebar lists every tutorial so you can switch. This means:
- The tutorial guides remain the single source of truth: you edit them in place, and the site picks up the changes on the next build.
- Notebooks are rendered statically in the browser, with no Jupyter/Python requirements at build time (the converter is plain Node).
- Relative links between guides (and images like
img/*.png) keep working because original filenames are preserved.
How fresh is this site
Every page footer shows a Last site build badge with the date and time
(in Pacific time) at which the published site was generated. Because the site is
rebuilt by GitHub Actions on every push to main, that timestamp is an
accurate indicator of how recently the tutorial pages were regenerated from
the sources.
Build steps
cd website
npm install
npm run sync # regenerate tutorials/ + sidebars from the tutorial sources
npm run start # local development server
npm run build # production build into website/build
Deployment
A GitHub Actions workflow (.github/workflows/docs.yml) builds the site and
publishes it to GitHub Pages on every push to main. The Docusaurus
baseUrl in website/docusaurus.config.js is /cloudbank_showcase/, which
matches the <org>.github.io/cloudbank_showcase/ host. To host elsewhere
(e.g. a custom domain), update url/baseUrl there.
Limitations / possible next steps
- Notebook outputs are rendered as static text/images; interactive widgets (e.g. Plotly) are not embedded.
- Autogenerated documentation for shell scripts (e.g.
scripts/*.shin the chemistry tutorial) is not included yet. - The site has no Algolia search index configured.