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 from gh-pages branch-based deployment (using peaceiris/actions-gh-pages) to the modern GitHub artifacts-based approach (using actions/deploy-pages). During this transition, most lecture repositories still use the gh-pages branch workflow while lecture-dp has migrated to the artifacts-based approach. See the lecture table for details.

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

   

3. Click on Draft a new release

   

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

   

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

   

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:

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:

macOS

brew install gh

Linux

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.

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 Repositories still using gh-pages Deployment

Most current QuantEcon lecture repositories listed below still deploy via the gh-pages branch using peaceiris/actions-gh-pages. Some repositories, such as lecture-dp, have already migrated to the artifacts-based GitHub Pages workflow. For the repositories in this table, the publish workflow is triggered by pushing a tag matching publish*.

Repository	Website	Action
lecture-python-intro	intro.quantecon.org	peaceiris/actions-gh-pages@v4
lecture-python-programming	python-programming.quantecon.org	peaceiris/actions-gh-pages@v4
lecture-python.myst	python.quantecon.org	peaceiris/actions-gh-pages@v4
lecture-python-advanced.myst	python-advanced.quantecon.org	peaceiris/actions-gh-pages@v4
lecture-jax	jax.quantecon.org	peaceiris/actions-gh-pages@v4
lecture-datascience.myst	datascience.quantecon.org	peaceiris/actions-gh-pages@v4
lecture-julia.myst	julia.quantecon.org	peaceiris/actions-gh-pages@v4

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.

   Linux

   chrome lectures/_build/html/index.html
   

   or if you are editing in the lectures folder

   chrome _build/html/index.html
   

   macOS

   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