How mpi-astronomy/faq works
Project type and purpose
• This is a static documentation website (“MPI-astronomy FAQ”) built with the Jupyter Book (MyST) ecosystem. Its sole purpose is to collect and publish short FAQ-style documents (Markdown + Jupyter notebooks) on astronomy-related computing topics.
File structure
• Top-level files:
• .github/workflows/deploy-myst.yml → CI/CD pipeline for building & deploying the site
• myst.yml, pyproject.toml, requirements.txt → project configuration & dependencies for Jupyter Book
• README.md, LICENSE, CONTRIBUTING.md, etc. → repository metadata
• Content directory:
• faq/ → Jupyter Book source tree containing _config.yml, chapter TOC (_toc.yml), Markdown chapters and .ipynb notebooks
• No traditional “backend” or “database”—the site is generated purely from file-based source.
README for additional insights
• Confirms use of Jupyter Book (MyST Markdown + notebooks) and the executablebooks/cookiecutter-jupyter-book template
• Deploys via a GitHub Actions workflow to GitHub Pages at https://mpi-astronomy.github.io/FAQ/
Main components & relationships
a. Source Repository (GitHub)
• Stores all content (faq/), configuration (myst.yml, _config.yml), build scripts, and CI definitions.
b. Static Site Generator (Jupyter Book)
• Reads the MyST Markdown and notebooks, applies templates, and produces a static HTML/CSS/JS site.
c. CI/CD Pipeline (GitHub Actions)
• On push/merge, runs deploy-myst.yml, installs dependencies, invokes jupyter-book build, and publishes output to the gh-pages branch.
d. Hosting (GitHub Pages)
• Serves the generated static site to end users at the public URL.
e. End Users
• Browse the FAQ in a web browser; no dynamic server or database involved.
Data Flow:
Developer → Git commit → GitHub Actions → Jupyter Book build → gh-pages branch → GitHub Pages → Browser
Architectural patterns & design principles
• Infrastructure as code: CI/CD pipeline fully defined in YAML
• Configuration-driven: All site behavior controlled via myst.yml & _config.yml
• Content-source separation: Raw documents in faq/ are separate from build logic
• Immutable hosting: Once built, site is static—no runtime code execution on the server