LHTML+ lhtml-site

lhtml-site : installation et options

Cette page est en anglais : elle est lue dans README.md de drohmer/lhtml-site à chaque construction du site, et documente donc toujours la version actuelle.

Installation

pipx install lhtml-site                  # the command lhtml-site, in an environment of its own
pipx upgrade lhtml-site                  # later, to update it

Without pipx, in a virtual environment (Homebrew and recent system Pythons refuse a pip install outside one). On macOS and Linux:

python3 -m venv ~/.venvs/lhtml-site
source ~/.venvs/lhtml-site/bin/activate     # fish: activate.fish
python -m pip install lhtml-site

On Windows, in PowerShell:

py -m venv $HOME\.venvs\lhtml-site
& $HOME\.venvs\lhtml-site\Scripts\Activate.ps1
python -m pip install lhtml-site

The command lhtml-site is then there while that environment is active (the source or Activate.ps1 line again, in a new terminal). lhtml-site --version prints the installed version and the version of LHTML it runs. Development version: pipx install git+https://github.com/drohmer/lhtml-site.

Requirements: Python 3.11 or newer, on Linux, macOS or Windows. Installed with it: lhtml-markup (LHTML 3), Jinja2, jinja-markdown, markdown-it-py, pytidylib, pyyaml, rich. That is all a site of HTML pages or slides needs: no Node, no browser, no other program.

Optional features

Each optional feature needs its own tools. lhtml-site doctor says, for each feature, what it finds and the command that installs what is missing, for the way lhtml-site is installed:

Feature Needs
PDF export (slides-pdf) playwright and pypdf (Python, the extra lhtml-site[pdf]) and Playwright's Chromium: see PDF export
Layout report (--layout, --render) the same playwright and Chromium
Formulas rendered at build quickjs (Python, the extra lhtml-site[math]): see Formulas
Videos in several codecs (cache_video_directory:) ffmpeg, and ffpb (Python)
SASS (.sass files) libsass (Python)
Figures in code (*.svg.py, *.svg.tex) the libraries their scripts import, such as matplotlib, numpy (Python); latex and dvisvgm (TeX Live)
Code of other repositories (code_include.py) git
HTML cleaned by tidy (use_tidy: true) the library libtidy

Python packages after pipx. pipx installs lhtml-site in an environment of its own: pip install matplotlib puts the package into another Python, where lhtml-site does not find it. Inject the packages into its environment instead:

pipx inject lhtml-site matplotlib numpy          # figures in code
pipx inject lhtml-site libsass                   # SASS
pipx inject --include-apps lhtml-site ffpb       # videos (a command: --include-apps)
pipx inject lhtml-site quickjs                   # formulas rendered at build

In a virtual environment or a checkout, pip install matplotlib numpy (and libsass, ffpb) in the Python that runs lhtml-site does the same.

Formulas

The themes render the formulas of a page with KaTeX: in the browser, or at build when quickjs is installed (no TeX source shown while the page loads, nothing for the PDF export to wait for):

pipx inject lhtml-site quickjs                   # after pipx
pip install "lhtml-site[math]"                   # in a virtual environment or a checkout

quickjs has wheels up to Python 3.12; on a newer Python pip compiles it, which needs a C compiler (Xcode command line tools, gcc, Visual Studio Build Tools). How the formulas are found and rendered, and the setting katex:, are in Formulas of the reference.

PDF export

The PDF export, and the layout report, run Chromium through Playwright for Python: two Python packages and a browser, no Node.js. After pipx install lhtml-site:

pipx inject lhtml-site pypdf
pipx inject --include-apps lhtml-site playwright
playwright install --only-shell chromium         # Playwright's Chromium, about 200 MB, once
lhtml-site doctor                                # PDF export (...): ready

--include-apps puts the playwright command of lhtml-site's environment on your PATH, so that the browser downloaded is the one its Playwright expects. If pipx warns that another playwright is already on your PATH, run the command that lhtml-site doctor gives instead. In a virtual environment or a checkout: pip install "lhtml-site[pdf]", then python -m playwright install --only-shell chromium. On Linux, Playwright may also ask for the system libraries of Chromium: playwright install-deps chromium. The configuration key chrome names a Chromium or Chrome already installed, to use instead of the download.

What the export writes and how it waits for each slide are in PDF export of the reference.

From a checkout

A clone, or a submodule of a project:

git clone https://github.com/drohmer/lhtml-site.git
cd lhtml-site
pip install -r requirements.txt
python generate.py ...            # the same as lhtml-site ...

generate.py at the root of the repository runs the lhtml-site of the checkout (its code is in src/lhtml_site/), so the projects that include it as a submodule call python <submodule>/generate.py, and keep naming its files as <submodule>/themes/slides/ or <submodule>/plugins/pre_include.py (they are found in src/lhtml_site/). pip install -e . in a checkout installs the command from it.

The checkout also holds a complete demo, a course website with its videos, in src/lhtml_site/example/ (not installed by pip: too heavy). To build it:

mkdir demo
cp -r src/lhtml_site/example demo/src
python generate.py init demo
cd demo
python ../generate.py --serve --watch

The tests, the locked dependencies and the layout of the repository are in Development.

Construit avec lhtml-site, thème docs. Fait partie de ScholarTools.