Skip to main content

Getting Started with PreTeXt

Geoff Cox, Ph.D.

Section Part 8. Deploy to a Public Web Page

Deploying means publishing your built HTML at a real URL that anyone can visit. GitHub provides free hosting for this through a service called GitHub Pages. There’s a one-time setup step and then a single command does the rest.
🔗

One-time setup: turn on GitHub Pages.

  1. Open your repository page on github.com in a new tab.
    🔗
    🔗
  2. Click Settings in the top row of tabs on that page.
    🔗
    🔗
  3. In the left sidebar, click Pages (under “Code and automation”).
    🔗
    🔗
  4. Under Source, use the dropdown to select GitHub Actions. You’ll not need to configure a workflow by hand; the PreTeXt deploy command will handle that for you.
    🔗
    🔗
  5. That’s it. No save button to press, the setting takes effect immediately.
    🔗
    🔗
🔗
🔗

Deploy your site.

Back in your Codespace:
🔗
  1. Click ▷ PreTeXt on the blue bar.
    🔗
    🔗
  2. Choose Deploy. (If you don’t see it, first commit and sync any pending changes from Part 7, then try again.)
    🔗
    🔗
  3. Watch the terminal. Several things happen in sequence: a build, a push to a special gh-pages branch, and a trigger of the GitHub Actions workflow that actually publishes the site.
    🔗
    🔗
  4. When the command finishes, the terminal will print your public URL. It looks like:
    🔗
    https://YOUR-USERNAME.github.io/YOUR-REPO-NAME/
    🔗
    🔗
  5. The site itself may take another minute or two to actually go live even after the command finishes. You can check progress by going to your repository on github.com and clicking the Actions tab; a green checkmark means it’s up.
    🔗
    🔗
🔗
🔗

✓ You know it worked when….

You can open the github.io URL in a fresh browser tab (or on your phone, or from a friend’s laptop) and see your lesson live on the public internet.
🔗
🔗

If you get stuck: the URL shows a 404.

Two usual causes. First, give it another two or three minutes; the initial publish sometimes lags behind the deploy command. Second, go to Settings → Pages and confirm the source really is set to GitHub Actions. If it still says Deploy from a branch, change it, then run Deploy one more time.
🔗
🔗

If you get stuck: deploy command fails with a permissions error.

On your repository page, go to Settings → Actions → General, scroll to Workflow permissions, and make sure Read and write permissions is selected. Save. Return to the Codespace and run Deploy again.
🔗
🔗
🔗
PrevTopNext