Skip to content

tips

How to create this note?

  1. Write articles by Markdown.
  2. Build and preview the Jupyter Book 2 site.
  3. Publish the generated HTML with GitHub Pages.

TL;DR

This repository uses Jupyter Book 2 / MyST. Build and preview are separate steps:

  • jupyter-book build --site prepares the local site data used by the preview server.
  • jupyter-book start starts the local preview server.
  • jupyter-book build --html --ci generates static HTML under _build/html for GitHub Pages.

このリポジトリは Jupyter Book 2 / MyST を使っている。build と preview は 分けて考える。

  • jupyter-book build --site: ローカル preview server 用の site data を生成する。
  • jupyter-book start: ローカル preview server を起動する。
  • jupyter-book build --html --ci: GitHub Pages へ公開する静的 HTML を _build/html に生成する。

Directory structure

├─ src
│  ├─ index.md
│  └─ ...
├─ myst.yml
└─ requirements.txt

Local preview

jupyter-book build --site
jupyter-book start --port 3000

Then open http://localhost:3000.

Build static HTML for publishing

BASE_URL=/jb-notes jupyter-book build --html --ci

The generated static site is written to _build/html.

Publish

Publishing is handled by GitHub Actions:

  1. Install Python dependencies from requirements.txt.
  2. Run jupyter-book build --html --ci.
  3. Push _build/html to the gh-pages branch with ghp-import.

This matches the current GitHub Pages setting where deployments are allowed from the gh-pages branch.

References: