Yavi Theme — Documentation

Complete documentation for the Yavi theme family for TYPO3 v14: yavi_core (the framework) and the theme built on it, yavi_lucerne.

Written for three kinds of reader, in this order:

• Integrators who install and configure a site.
• Editors who work with the content elements every day.
• Developers who extend the theme or build a new one.

Table of contents

Getting started

Configuration

Working with content

Extending

Watch it first

The video loads from YouTube only once you press play — nothing is requested before that (why).

Two more walkthroughs sit in the chapters they belong to: the installation with the installer and DDEV, and the hero carousel from gradient overlay to text animation. All of them are on the Yavi Themes channel.

The 30-second version

# packages/yavi-core and packages/yavi-lucerne unpacked from the ZIP,
# ./packages/* registered as a path repository in composer.json
composer require webagentur-yahya/yavi-core:dev-main \
                 webagentur-yahya/yavi-lucerne:dev-main
vendor/bin/typo3 extension:setup
vendor/bin/typo3 cache:flush

The version is dev-main because the packages come from a ZIP and not from a tagged repository — the installation chapter has the full composer.json.

Then, in the backend:

1. Site Management → Sites → your site → Sets: activate yavi-lucerne/full.
2. Yavi Theme → Licence: enter the licence key. Without a valid licence the extension does not work.
3. Yavi Theme → Design / Colors: set your brand colours.

Everything else is detail — and that detail is what the rest of this documentation is about.

Conventions used here

• yavi_core is the extension key, webagentur-yahya/yavi-core the Composer name.
• Paths starting with packages/ refer to a Composer-mode installation with the extensions in the project's packages/ directory — the layout the delivered ZIP already has.
• The extensions are delivered as a ZIP from licence.yavithemes.com, not from packagist and not from a Composer registry. Updates come from the same place.
• Commands are written for DDEV (ddev exec …); drop the prefix on a normal server.
• "Theme" always means an extension like yavi_lucerne. yavi_core is not a theme — it is the framework the themes are built on.

Impressions

All screenshots in images/ come from a running installation (TYPO3 14.3, Yavi Lucerne), taken at 1600 CSS px — 390 px for the mobile ones — with a 2× device pixel ratio, so they stay sharp on retina displays. The PNGs are the originals; the pages reference the .webp copies next to them.

They are generated, not taken by hand:

cd packages/yavi-core/Build
node --experimental-websocket screenshots.mjs

The script drives Chrome over the DevTools Protocol, creates a throwaway admin in light mode, walks every backend module and frontend page in the list at the top of the file, and deletes that admin again. Pass file names to redo only some of them. Re-run optimize-images.py afterwards.

Reading this documentation

Two formats, one source:

• Markdown — the .md files in this folder, readable in any editor or on a git host.
• HTML — open index.html. Dark reading layout, sidebar, per-page table of contents and a search that works even when you open the file directly from the folder (no server needed).

The documentation is also available in German, at /de/ — the EN / DE switch at the top right of every page leads to the same chapter in the other language.

Rebuild the HTML after editing a chapter:

python3 build.py

It writes one .html per .md, plus assets/docs.css, assets/docs.js and the search index. No Node, no toolchain — the same rule the theme itself follows.

Blockquotes become callouts. The build guesses the severity from the wording, which is good enough for most notes; start the quote with !! when you need the loud red one and do not want to rely on the guess:

> A plain note becomes a lime "info" callout.
> Wording like "never" or "must" makes it a rose "warning" callout.
> !! **This becomes the large danger callout** — for the few places where
> getting it wrong destroys data.

Two more scripts, both run only when their input changes:

python3 optimize-images.py   # new screenshots in images/ → .webp
python3 fetch-fonts.py       # re-download the webfonts into assets/fonts/

optimize-images.py needs cwebp (brew install webp) and skips anything already converted. fetch-fonts.py exists so the pages never call fonts.googleapis.com — a documentation site for a theme that self-hosts its fonts should do the same. Run it only to pick up a new font version.

Publishing

The pages are published at docs.yavithemes.com with Deployer — the same tool the theme and the licence server use. One command does the whole chain:

dep deploy live

In order: build.py runs, the result is committed and pushed to GitLab, the server checks that state out into a new release, and the release is symlinked to current. Finally the live URL is fetched once to confirm it answers.

Because the server deploys what is in GitLab, the HTML has to be committed — so dep deploy asks for a commit message whenever the working tree is dirty and refuses to continue if you decline. Nothing is deployed that is not on main.

Individual steps, when you want only one of them:

dep docs:build live    # rebuild the HTML, nothing else
dep docs:push live     # commit and push, without deploying
dep docs:images live   # new screenshots in images/ → .webp
dep docs:status live   # which commit is live, how many pages
dep docs:verify live   # does the live URL answer with 200?
dep rollback live      # back to the previous release

deploy.php and hosts.yml hold the configuration. Two things are worth knowing about it:

• The DocumentRoot of the domain points at /docs.yavithemes.com/current. The site lives at the root of the repository — index.html is at the top, not in a public/ folder — so there is no webroot below the release. As long as it points anywhere else, the host's placeholder page answers with a perfectly healthy 200, which is why docs:verify checks the content and not the status code.
• The subdomain needs its own Let's Encrypt certificate. Without one the server falls back to the hoster's *.sui-inter.net certificate and every client rejects the name.
• clear_paths strips what a web server has no use for: the Python scripts, the deploy configuration and the PNG originals in images/. The pages only ever reference the .webp copies, so the originals stay in git and never reach the server.

There is no CI pipeline and nothing to install on the server: no Composer, no Node, no Python. The same rule as everywhere else here.