The Island of TeX website #

The website at https://islandoftex.gitlab.io uses Zola 0.23.6 and the DevLab theme, pinned to v0.9.0 as a Git submodule. The site uses the Island visual identity, with visual design by Paulo Cereda.

Develop and verify #

git submodule update --init --recursive
git lfs pull
nix develop
zola serve

The locked shell supplies Zola, Bash, Awk, Git/Git LFS, curl, certificates and GNU sed. CI uses this same environment. Site customizations live in templates/, sass/site.scss and static/; the theme checkout stays unmodified. Do not create a site main.css or sass/main.scss: DevLab owns that stylesheet.

nix develop -c bash tests/identity.sh
nix develop -c bash tests/publishing.sh
nix develop -c bash tests/lfs-assets.sh
nix develop -c bash scripts/check-theme-pin.sh
nix develop -c zola check --skip-external-links
nix develop -c zola build
nix build

nix build (also nix build .#website) creates deployable static files at result/. For a different deployment origin or subpath:

nix build --impure --expr '
  let site = builtins.getFlake (toString ./.); in
  site.packages.${builtins.currentSystem}.website.override {
    deploymentUrl = "https://example.org/island/";
  }
'

--impure resolves the local flake and host system; the package build stays sandboxed. The URL controls canonical links, feeds and local asset URLs. Stage new files before Git-based flake builds so Nix includes them. Run nix fmt for Nix formatting and nix flake check --no-build for evaluation.

Content and publishing #

The Tools and Libraries hubs are data-driven from content/community/{tools,libraries}/_index.md; the homepage selects featured entries from those hubs. Project detail pages are available under /community/projects/. Community pages use DevLab's named documentation collection. Publication cards are defined by content/publications/_index.md and rendered with a site-owned template.

GitLab Pages runs:

nix develop --no-write-lock-file -c bash scripts/build-ci-site.sh

Run that command only in a disposable checkout. It imports pinned upstream arara news and appends remote project READMEs, then normalizes headings, checks internal links and builds public/. Downloads follow redirects, reject HTTP errors and empty responses, and have connection/total time limits. Each download completes before append; failures stop publishing. The package includes repository content and pinned news, but does not perform live README imports.

Imported news retains its metadata and Markdown, with a link to the original article. Remote news and READMEs skip Tera content templating so code examples remain literal. Bash regression tests cover import and heading behavior.

Theme updates #

Keep themes/devlab-theme and the devlab flake input at the same revision. Update the submodule, flake URL and lock deliberately, then run scripts/check-theme-pin.sh, the normal checks and browser checks. Read DevLab's release notes before changing the pin.

Prefer CSS tokens and small template slots over copying the shared shell.

License #

• Site templates and theme customizations are MIT licensed. DevLab retains its own MIT license and third-party notices in its submodule.
• Decorative icons use Tabler Icons under MIT; see static/icons/SOURCES.md and static/icons/Tabler-LICENSE.txt for sources and licensing.
• Static content is all rights reserved unless otherwise stated. KaTeX assets retain their distribution license in static/fonts/KaTeX-LICENSE.txt.
• Karla, Rosario, Expletus Sans and Cascadia Code use the SIL Open Font License; see static/fonts/OFL.txt. Fonts are served locally with font-display: swap.
• Project descriptions in content/community/{projects,tools,libraries} use their respective project licenses.
• The vision and members pages (island.md, members.md) use CC BY-NC-ND 4.0.
• Remaining website content uses CC BY 4.0.

Vendored project news #

The arara-news flake input pins the upstream news at a specific commit. Both nix build and the CI publishing script import those articles, preserving their original metadata, URLs and attribution. No network is used inside the package build. Update the input revision and flake.lock deliberately to import new upstream articles. README descriptions remain live CI imports.

For a local zola serve preview with project news, run:

nix develop -c bash scripts/import-project-news.sh
nix develop -c zola serve

The generated articles live in content/blog/ for that working checkout; use a disposable checkout for import/build verification. tests/site-output.sh checks that packaged and CI outputs contain the four known upstream articles, feed entries, featured logos and internal card destinations.

Binary asset storage #

Track every binary font (OTF, TTF, WOFF and WOFF2) and raster image/icon in Git LFS. SVG source, TeX, CSS, JavaScript, configuration and license text remain diffable Git files, except static/favicon.svg, which is stored in LFS. Submodules retain their upstream policies.

After staging files, run nix develop -c bash tests/lfs-assets.sh. CI runs this same audit before building: it examines the index's real blobs, rejects binary files without LFS attributes, rejects non-pointer blobs even when attributes say LFS, and rejects assets that have not been materialized by Git LFS.

Visual identity #

The visual identity is defined in iot-trove/artwork/texmf/ by islandoftex-colors.sty, islandoftex-fonts.sty and sample.tex. sass/_identity.scss maps the five source colors to DevLab and the island illustration. Black and white are permitted by the guide; gradients, opacity and white tints derive from these colors, rather than additional hex values. tests/identity.sh rejects new literal colors in site-owned paint sources. Third-party/project logos and publication artwork retain their original colors.

Body text uses Karla Light with old-style numerals, headings Rosario Light, display titles Expletus Sans, and code Cascadia Code Light. Math uses the unmodified FiraMath-Light.otf from the identity's font directory (embedded copyright: © 2018–2022 Xiangdong Zeng; SIL OFL 1.1 in static/fonts/FiraMath-LICENSE.txt). KaTeX converts TeX to native MathML so browsers can lay equations out with Fira Math's own OpenType math metrics. All fonts remain local and LFS-tracked. The DevLab submodule is unmodified; site CSS also overrides its fixed copy-status colors and menu backdrop.

TeX wordmarks use the site-owned island.wordmark Zola component and CSS spacing from islandoftex-fonts.sty. Templates pass plain text explicitly; authored Markdown may use {{<island.wordmark text="LaTeX" />}}. The component escapes text before adding its fixed markup, and copying retains the original spelling. It does not rewrite prose, code, MathML or search results.

The site includes project hubs and featured cards, an animated island hero, publication cards, community and contributor pages, a Code of Conduct, a lighthouse 404 page and a paginated blog. Shared styling covers the footer wave, wordmarks, theme transitions, reduced motion and print output.