Publishing CUPiD notebooks

Publishing CUPiD notebooks#

The html/ directory generated by cupid-webpage can be shared manually or published as a website.

Publishing to GitHub.io#

To facilitate sharing, cupid-webpage can be configured to automatically push to a GitHub repo, which can then generate a GitHub.io website.

Setting up your GitHub repo#

Start by creating a fresh GitHub repository.

  • Make sure to give it a good name! Let’s say you name it my-repo. While the GitHub repo you create will be at https://github.com/yourusername/my-repo, the URL you’ll give people to view the published website will be https://yourusername.github.io/my-repo.

  • Set the latter URL as your repo description.

  • In case someone accidentally winds up on your repo instead of the published website, you may want to add a README.md with something like “This repository contains CUPiD outputs. You’re probably more interested in the website version, at https://yourusername.github.io/my-repo.”

Once that’s done, go to your repo’s Settings > Pages screen.

  1. For Source, choose “GitHub Actions”.

  2. If you see the “Static HTML” workflow, press Configure. Otherwise, press “browse all workflows”, find it there, and press Configure.

  3. Add git lfs support. You should see something like the following:

    steps:
      - name: Checkout
        uses: actions/checkout@v4

Add two lines so it looks like this (be careful to include the spaces at the beginning of each line):

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          lfs: true

  1. Press Commit Changes and handle the dialog box that pops up.

Cloning and preparing your GitHub repo#

Next, you’ll need to clone your repo to the machine where you’re running CUPiD.

  1. On that machine, navigate to where you want the repo to be cloned. This should be outside your local copy of the CUPiD repo!

  2. Clone your repo.

  3. cd into your repo.

You should now be in the directory /path/to/my-repo/.

Next, we’re going to enable Git Large File Storage (git lfs). This makes it so that large binary files (things like images) will be given special handling, including a feature to make it more lightweight to clone your repo in the future. (Note that these steps will only need to be performed once, not every time you clone it.)

  1. Do git lfs install.

  2. Create a text file, .gitattributes, with the following lines:

*.pdf filter=lfs diff=lfs merge=lfs -text
*.png filter=lfs diff=lfs merge=lfs -text
*.jpg filter=lfs diff=lfs merge=lfs -text
*.jpeg filter=lfs diff=lfs merge=lfs -text
*.pickle filter=lfs diff=lfs merge=lfs -text
*.svg filter=lfs diff=lfs merge=lfs -text
*.ttf filter=lfs diff=lfs merge=lfs -text
*.woff2 filter=lfs diff=lfs merge=lfs -text
*.mo filter=lfs diff=lfs merge=lfs -text
*.map filter=lfs diff=lfs merge=lfs -text

  1. git add .gitattributes

  2. git commit -m "Enable git lfs."

Publishing your notebook#

Once all that’s done, publishing is as simple as calling cupid-webpage with two extra options:

  • -g/--github-pages-dir: The path to the directory where you cloned your repo.

  • -n/--name: The name you want to give to this published version of your notebook.

So, e.g.:

cupid-webpage -g /path/to/my-repo/ -n my-first-published-notebook

This will produce a bit of extra printout at the end, something like:

Done! Published to https://yourusername.github.io/my-repo/versions/my-first-published-notebook
It might take a bit for GitHub.io to generate that URL

You can share that URL with someone for them to see the published version of that notebook. You can also share https://yourusername.github.io/my-repo if you want them to see a list of all the versions you’ve published.

Contents