LHTML+ lhtml-site

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.

Needs: lhtml-site installed and a site that builds; for GitHub Pages, a GitHub accountTime: 15 to 30 minYou get: your site at a public address

Anywhere: copy .site/

  • Without a server: open .site/index.html from 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

  1. Put the project in a GitHub repository: commit configure.yaml and src/, not what the build writes. First write a .gitignore file next to configure.yaml, which keeps the build outputs out:

    /.site/
    /.structure/
    /.verification/
    /.layout/
    /.feedback/
    /code/
    /slides.pdf
    /images/
    

    .layout/ is the report of lhtml-site --layout; .feedback/ holds the comments written on the pages during lhtml-site --serve; slides.pdf and images/ are what the slides-pdf theme writes next to configure.yaml; code/ is the repositories cloned by the code_include.py plugin. 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.

  2. Add this file, which builds the site at each push on main and 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
    
  3. 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), commit cache_video/ too: the build reuses the converted videos, and needs no ffmpeg on GitHub.
  • With the docs theme, add the search index to the run line: pip install lhtml-site 'pagefind[extended]' && lhtml-site && python -m pagefind --site .site.
  • With a pdf target (theme slides-pdf), the workflow needs Playwright and its Chromium: replace the run line with pip 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-site run on your computer usually shows the same error.
  • The 404 page has no style, or its links lead nowhere: base_url does 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.

Built with lhtml-site, the docs theme. Part of ScholarTools.