Put it online
The site is the directory .site/: static files, no database, no program to run on the server.
Copy it anywhere that serves files. Its pages link to each other with relative links, so the site
works at any address, at the root of a server or deep below it.
Anywhere: copy .site/
- Without a server: open
.site/index.htmlfrom the disk, or send the directory in a zip. - A server you can reach with ssh (often the case at a university), build, then copy:
lhtml-site rsync -av --delete .site/ me@server:/var/www/my-course/
The slash after .site/ copies its content, not the directory itself; --delete removes the files
that the site no longer has. On a university server, the directory is often ~/public_html/,
served at https://www.my-university.edu/~me/: ask your IT service. A program such as FileZilla
copies the files as well.
.site/ is hidden, as any name starting with a dot: Cmd+Shift+. shows it in the macOS Finder,
View > Hidden items in the Windows explorer.
GitHub Pages
-
Put the project in a GitHub repository: commit
configure.yamlandsrc/, not what the build writes. First write a.gitignorefile next toconfigure.yaml, which keeps the build outputs out:/.site/ /.structure/ /.verification/ /.layout/ /.feedback/ /code/ /slides.pdf /images/
.layout/is the report oflhtml-site --layout;.feedback/holds the comments written on the pages duringlhtml-site --serve;slides.pdfandimages/are what theslides-pdftheme writes next toconfigure.yaml;code/is the repositories cloned by thecode_include.pyplugin. A line for a file you do not have does no harm.New to git? GitHub Desktop does it with buttons: File > Add local repository, choose the project directory (it offers to create the repository), Commit to main, then Publish repository; after each change, Commit and Push origin.
-
Add this file, which builds the site at each push on
mainand publishes it:# .github/workflows/pages.yml on: {push: {branches: [main]}, workflow_dispatch: {}} permissions: {contents: read, pages: write, id-token: write} jobs: deploy: runs-on: ubuntu-latest environment: github-pages steps: - uses: actions/checkout@v7 - uses: actions/setup-python@v7 with: {python-version: '3.12'} - run: pip install lhtml-site && lhtml-site - uses: actions/upload-pages-artifact@v5 with: {path: .site} - uses: actions/deploy-pages@v5
-
In the repository settings, under Pages, choose GitHub Actions as the source.
After the next push, the Actions tab shows the build, and the site is at
https://me.github.io/my-course/ (your account, then the name of the repository).
- With videos (
cache_video_directory), commitcache_video/too: the build reuses the converted videos, and needs no ffmpeg on GitHub. - With the
docstheme, add the search index to therunline:pip install lhtml-site 'pagefind[extended]' && lhtml-site && python -m pagefind --site .site. - With a
pdftarget (themeslides-pdf), the workflow needs Playwright and its Chromium: replace therunline withpip install "lhtml-site[pdf]" && python -m playwright install --with-deps --only-shell chromium && lhtml-site.
The 404 page (theme docs)
The docs theme can write a 404.html, the page shown for an address that leads nowhere. It needs
to know where the site is served, in configure.yaml:
base_url: '/my-course/'
/ at the root of a server, /my-course/ for https://me.github.io/my-course/,
/~me/my-course/ for a university page, or a whole URL ending with /. The 404.html then works
at any depth. GitHub Pages and Netlify serve it by themselves; for nginx:
error_page 404 /my-course/404.html;, for Apache (a .htaccess file):
ErrorDocument 404 /my-course/404.html.
Without base_url, and with the other themes, there is no 404.html: the server shows its own.
More in the docs theme.
Search (theme docs)
The search box needs its index, built after the site:
lhtml-site python -m pip install 'pagefind[extended]' python -m pagefind --site .site
Run the pip line in a virtual environment: Homebrew and recent system Pythons refuse it outside
one. With Node.js, npx pagefind --site .site does the same.
Each build replaces .site/, and its index with it: run pagefind again after each build. The
search works when the site is served over http, not from a file opened on the disk. To try it,
serve the directory as it is, without rebuilding it: python3 -m http.server -d .site, then
http://localhost:8000/.
If it goes wrong
- The Actions tab shows a red build: open it, the failing step says why; the same
lhtml-siterun on your computer usually shows the same error. - The 404 page has no style, or its links lead nowhere:
base_urldoes not match the address of the site; it must start and end with/. - The site works on the disk but not online: check that you copied the content of
.site/, not the directory itself (the slash in.site/).
Next: Themes, to change the look of the site.