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.