Using GitHub Pages to host a locally built site

Something I recently ran into: How do you build a site locally and host the resulting built version of the site on GitHub Pages? Here’s one way to do it. First, have a make all target that builds the public files from the source pages (for example, pass CommonMark filenames to Pandoc to get HTML.) Then make deploy does several things:

1. Make a fresh build directory and copy the source files, the Makefile, and the .git directory into it.
2. Run make gh-pages inside the build directory. That target depends on the all target, so this builds the site inside the directory.
3. Next, make gh-pages inside the build directory commits the public files on the gh-pages branch, then force pushes to GitHub.
4. Back in make deploy, delete the build directory. That includes the .git directory inside, so no history of built files gets preserved.

# We make this site with "make" locally and deploy generated pages to GitHub in
# a branch. First, delete the build directory and the gh-pages branch. Then
# copy the site files into the build directory and make the gh-pages target
deploy : all
    (git branch -D gh-pages || true) &> /dev/null
    rm -rf build && mkdir -p build
    cp -a Makefile .git $(SOURCES) build
    make -C build gh-pages
    rm -rf build

# This target only runs inside the build directory and does a commit and push
# on the gh-pages branch. If you look at this project on GitHub you should see
# the original .md files on the main branch and the generated HTML files on the
# gh-pages branch.
gh-pages : all
    basename `pwd` | grep -q build || exit 1
    rm -f .git/hooks/pre-push
    git checkout -b gh-pages
    git rm -f $(SOURCES)
    git add -f $(PUBLICFILES)
    git commit -m "this is a temporary branch, do not commit here."
    git push -f origin gh-pages:gh-pages

This is from a Makefile for a very basic .org site. The -C option to make is to change to the given directory before reading the Makefile. (That site has versioning for the source files on GitHub too, but it doesn’t have to be.)

Another option is to put the built files in a subdirectory, but then you end up committing the built files on the main branch: Using different static site generators · community · Discussion #21563

Related

colophon More about how this site is made

Bonus links

hangout_services/thunk.js It turns out Google Chrome (via Chromium) includes a default extension which makes extra services available to code running on the *.google.com domains

Even Amtrak was surprised by the instant popularity of its new Chicago-Twin Cities route (how is this surprising? Who actually likes air travel or taking most of a day to drive between Midwestern USA cities?)

Microsoft-owned adtech Xandr accused of EU privacy breaches (among the fun parts about this story is that they’re not bottlenecked on Ireland—noyb.eu figured out a way to file the complaint in Italy)

A high-level view of all of this feed reader stuff (good info about a useful QA service for making your RSS tool better behaved. The script that builds the links for this bonus links section just got fixed up some.)

Design for the People: The US Web Design System and the Public Sans Typeface To ensure clear and consistent typography, the free and open-source typeface Public Sans was created for the US government.

Download the Atkinson Hyperlegible Font | Braille Institute Atkinson Hyperlegible font is named after Braille Institute founder, J. Robert Atkinson. What makes it different from traditional typography design is that it focuses on letterform distinction to increase character recognition, ultimately improving readability. (If I use a hyperlegible typeface, I can make my prose more confusing, right?)

The Itanic Saga (personally I had no idea that a story about Intel Itanium would start in 1923)

Amazon Is Investigating Perplexity Over Claims of Scraping Abuse Amazon’s cloud division has launched an investigation into Perplexity AI. At issue is whether the AI search startup is violating Amazon Web Services rules by scraping websites that attempted to prevent it from doing so, WIRED has learned.