Publishing Lectures

Publishing Lectures#

This page provides instructions on how to update the live content that is hosted on GitHub Pages. GitHub Pages is a service provided by GitHub that acts as a host for static web sites, such as those generated by jupyter-book.

There are three publishing pathways available:

  1. Build and Publish via GitHub Release

  2. Tagging a Release with the GitHub CLI

  3. Building Locally and Push to GitHub Pages

Note

QuantEcon is transitioning away from gh-pages branch-based deployment (using peaceiris/actions-gh-pages) towards the native GitHub Pages artifact deployment (using actions/deploy-pages).

The target architecture is the reusable quantecon/actions library, which wraps the native artifact deployment in a publish-gh-pages action; lecture-dp is the reference implementation. A small number of repositories (e.g. lecture-python-programming) already deploy via the native artifact path with inline workflow steps, while most lecture repositories still use the legacy gh-pages branch workflow. See the lecture deployment table for the current per-repo status.

Build and Publish via GitHub Release#

You can use GitHub Actions to build the main branch and publish directly to GitHub Pages by tagging a New Release as a web based workflow.

QuantEcon repositories are also setup to provide previews of the html when submitting changes either via pull request or main branch updates.

Workflow#

To build and publish the current main branch you create a GitHub release:

  1. Use your browser and open the repo page on GitHub such as lecture-python.myst

  2. Click on Releases

    ../_images/github-releases.png

  3. Click on Draft a new release

    ../_images/github-draft-new-release.png

  4. You will see an empty tag field and title field

    ../_images/github-new-release.png

  5. Add a tag following the pattern publish-<date> such as publish-2021march16 and update the title such as PUBLISH: 16th March 2021.

    ../_images/github-add-release-info.png

  6. Click on Generate release notes to auto-populate the description field with a summary of commits and contributors since the last release. This is a built-in GitHub feature that provides a changelog of pull requests merged and new contributors.

    Tip

    You can customise the auto-generated release notes by adding a .github/release.yml file to the repository. See the GitHub documentation for details on configuring categories and exclude labels.

  7. Click on Publish Release

You can check the status by clicking on the orange circle:

../_images/github-publish-status.png

once the status against the Build & Publish task turns green this indicates the build and publish workflow has been completed and the live site will be up to date within a couple of minutes.

Tagging a Release with the GitHub CLI#

The GitHub CLI (gh) provides a fast way to create a release and trigger the publish workflow directly from the terminal.

Prerequisites#

Install the GitHub CLI if you haven’t already:

brew install gh

conda install gh --channel conda-forge

Authenticate once with:

gh auth login

Workflow#

  1. Navigate to the lecture repository and ensure you are on main with the latest changes:

    cd ~/work/quantecon/lecture-python.myst
git checkout main && git pull

  2. Create a tag and release in a single command:

    gh release create publish-$(date +%Y%m%d) --title "PUBLISH: $(date +'%d %B %Y')" --generate-notes

    This will:

    • Create a new git tag (e.g. publish-20260415)

    • Generate release notes automatically from merged pull requests

    • Trigger the publish.yml GitHub Actions workflow

  3. Monitor the triggered workflow run:

    gh run watch

Tip

You can also create a release for a specific commit using the --target flag:

gh release create publish-$(date +%Y%m%d) --target <commit-sha> --title "PUBLISH: $(date +'%d %B %Y')" --generate-notes

Building Locally and Push to GitHub Pages#

Warning

This workflow should only be used as a fallback if the automated publish infrastructure (GitHub Actions) is failing. Prefer using a GitHub Release or the GitHub CLI under normal circumstances.

Important

This ghp-import fallback only applies to repositories that still deploy to the gh-pages branch (the peaceiris rows in the deployment table). Repositories that use the native artifact deployment (inline or via quantecon/actions) have no gh-pages branch, so this method does not apply to them — re-run their publish.yml workflow instead.

These instructions assume you are at the base level of a QuantEcon lecture repository such as lecture-python.myst

Note

QuantEcon uses the folder lectures to contain all jupyter-book documents

Lecture Deployment Status#

QuantEcon lecture repositories currently use one of three deployment paths. In all cases the publish workflow is triggered by pushing a tag matching publish* (see Build and Publish via GitHub Release and Tagging a Release with the GitHub CLI).

  • peaceiris (legacy) — deploys to the gh-pages branch via peaceiris/actions-gh-pages. This is used by most repositories.

  • native artifacts (inline) — deploys via actions/deploy-pages with build steps written inline in the repository’s publish.yml. No gh-pages branch.

  • quantecon/actions (target) — native artifact deployment composed from the reusable quantecon/actions library. No gh-pages branch.

Repository

Website

Deployment

lecture-python-intro

intro.quantecon.org

peaceiris (legacy)

lecture-python.myst

python.quantecon.org

peaceiris (legacy)

lecture-python-advanced.myst

python-advanced.quantecon.org

peaceiris (legacy)

lecture-jax

jax.quantecon.org

peaceiris (legacy)

lecture-datascience.myst

datascience.quantecon.org

peaceiris (legacy)

lecture-julia.myst

julia.quantecon.org

peaceiris (legacy)

lecture-python-programming

python-programming.quantecon.org

native artifacts (inline)

lecture-dp

dp.quantecon.org

quantecon/actions (target)

Note

This table is maintained by hand and lists the most active repositories. To confirm the deployment path for any repository, check the Deploy step in its .github/workflows/publish.yml.

Workflow#

  1. Activate the quantecon environment using conda:

    conda activate quantecon

    Warning

    Your software environment may change how the site is built. It is important to use the quantecon environment to ensure consistent html output.

  2. Build HTML files locally using jb build command

    jb build lectures

    or if you are editing files in the lectures folder you can use

    jb build ./

  3. Build IPYNB download notebooks locally using custom builder sphinx-tojupyter

    jb build lectures --builder=custom --custom-builder=jupyter

    and copy asset to _notebooks folder in _build/html

    mkdir lectures/_build/html/_notebooks
cp lectures/_build/jupyter/*.ipynb lectures/_build/html/_notebooks

  4. Build PDF book style pdf locally using the pdflatex builder

    jb build lectures --builder=pdflatex

    and copy asset to _pdf folder in _build/html

    mkdir lectures/_build/html/_pdf
cp lectures/_build/latex/*.pdf lectures/_build/html/_pdf

  5. You can preview the HTML by following the instructions displayed by jupyter book and open the index.html file located in your _build/html.

    chrome lectures/_build/html/index.html

    or if you are editing in the lectures folder

    chrome _build/html/index.html

    open lectures/_build/html/index.html

    or if you are editing in the lectures folder

    open _build/html/index.html

  6. Use ghp-import to sync the HTML files to the gh-pages branch using

    ghp-import -n -p -f -c <domain-name> -m <MESG> _build/html

    where:

    1. -n instructs github not to build your project using Jekyll,

    2. -p pushes the branch to origin/gh-pages, and

    3. -f forces the push to the repository to ensure the transfer is made.

    4. -c adds a CNAME file with the custom domain settings

    5. -m sets the commit message. Use a descriptive message such as publish-<date>

    ghp-import is a tool that will publish a directory of files such as the _build/html/ directory into the gh-pages branch of a repository and push them to github for publication. This tool will replace the gh-pages branch with the contents of what you point at it so it should be used carefully.

    Note

    If ghp-import is not installed you can do so using pip:

    pip install ghp-import

    this tool is provided in the quantecon environment

Additional details are provided in the jupyter-book documentation