Skip to main content

Architecture

Overview​

This website is developed using Docusaurus, an open-source static-site generator developed by Meta.

  • Static-site generator: Docusaurus
  • Repository: GitHub
  • CI: GitHub Actions
    • Runs the Jupyter notebook conversion and builds the entire website
    • Deploys to Vercel
  • Hosting: Vercel
    • Deployment is made to a subdomain (e.g., https://mysubdomain.minamiueda.com/docs/)
  • Reverse Proxy: Cloudflare Workers
    • To serve contents under the subdirectory of the domain root (at https://minamiueda.com/docs/), Cloudflare Workers is used to rewrite the request to the origin hosted at the subdomain.
    • It's just a matter of preference, but I wanted have them under subdirectory, not at subdomain, while maintaining other things managed as separate projects served from different servers.

All of the codes and documentation conents are published on GitHub.

Jupyter notebook​

Build system​

The customized build system supports Jupyter notebook as an input for documentation, in addition to the Markdown files. This allows the mixed usage of ipynb and mdx as the source of documentation.

Jupyter notebooks (.ipynb) are converted into Markdown files (.mdx) using a custom script in Python, which was originally forked from LangChain documentation repo. We use nbconvert to process the notebooks.

The conversion script notebook_convert.py supports:

  • Splitting a Jupyter notebook into multiple Markdown files (which are then built as separate pages in a chapter)
  • Extracting embedded output images and videos (e.g., jpg, png, svg, mp4) from the notebook
  • Excluding input cells and markdown/output cells from Markdown output (when {'hide_input': true} or {'hide': true})

See README.md for details on the notebook conversion.

Example​

Here are the example of the pages that were converted from a notebook.