Install and update

Install DevLab once, keep the selected version visible in your project and change that version only when you decide to upgrade. A tagged release gives every local machine and deployment the same theme files; the main branch does not.

The recommendation

Use a Git submodule when your Zola site is already stored in Git. It records the exact DevLab commit without copying the theme into your project history. Choose a vendored copy when your team deliberately avoids submodules.

Before you install

DevLab follows the current Zola release. Confirm that the supported version is available:

zola --version

This release expects Zola 0.23.6. Run the remaining commands from the root of your Zola site, where zola.toml lives.

Choose how the project stores DevLab

Method	Best fit	The version is recorded by...
Git submodule	Most sites already stored in Git	The parent repository's submodule pointer
Vendored copy	Teams that want every theme file in the site repository	The site's normal commits
Tagged clone	Build environments that fetch the theme separately	The checked-out tag in a nested repository

Pick one method. A tagged clone should not be committed as an embedded repository inside another Git project; use a submodule or vendored copy there.

Recommended: Git submodule

Add the theme repository.

git submodule add https://codeberg.org/RiPetitor/devlab-theme themes/devlab-theme

Select the stable release.

git -C themes/devlab-theme fetch --depth 1 origin tag v0.8.0
git -C themes/devlab-theme checkout --detach v0.8.0
git -C themes/devlab-theme describe --tags --exact-match

The final command should print v0.8.0. Detached HEAD is expected here: the site follows a release tag, not a development branch.

Enable DevLab in zola.toml.

theme = "devlab-theme"
compile_sass = true

Verify the site before committing the pointer.
```
zola check
zola build
```
Record the installation in the site repository.

Commit .gitmodules, themes/devlab-theme and your zola.toml change together. Another checkout can then restore the same theme version with:
```
git submodule update --init --recursive
```

Use git clone --recurse-submodules when cloning the complete site and its pinned theme in one command.

Alternative: vendored copy

A vendored copy is ordinary project code. It is easy for build services to consume and does not require submodule commands, but theme updates produce a larger project diff.

Download the source archive for v0.8.0 from the repository's Tags page.
Extract it as themes/devlab-theme/.
Add theme = "devlab-theme" and compile_sass = true to zola.toml.
Run zola check and zola build.
Commit the extracted files with the site.

The final directory must contain theme.toml directly inside the theme folder:

themes/
└── devlab-theme/
    ├── theme.toml
    ├── templates/
    ├── sass/
    └── static/

If an archive directory sits between devlab-theme/ and theme.toml, move the theme files up one level before building.

Deployment-only: tagged clone

Use a tagged clone when the surrounding project does not track the theme directory or the deployment workflow recreates it for every build:

git clone --branch v0.8.0 --depth 1 https://codeberg.org/RiPetitor/devlab-theme themes/devlab-theme

Do not run git pull inside this checkout to upgrade it. Select a new release tag explicitly so the chosen version remains reproducible.

Update a Git installation

Read the matching entry in Updates before changing versions. It tells you whether configuration, content components or template overrides need attention.

Make sure the installed theme is clean.
```
git -C themes/devlab-theme status --short
```
No output means it is safe to continue. If files are listed, stop and move those customizations into the site repository before switching releases.

Select the new tag.

Replace vX.Y.Z with the release you intend to install:

DEVLAB_VERSION=vX.Y.Z
git -C themes/devlab-theme fetch --depth 1 origin tag "$DEVLAB_VERSION"
git -C themes/devlab-theme checkout --detach "$DEVLAB_VERSION"
git -C themes/devlab-theme describe --tags --exact-match

Build before recording the upgrade.
```
zola check
zola build
```
Review the parts your site enables.

Open Home, Docs, Blog and Downloads when present. Check search, both color modes and any site-owned template or Sass overrides.
Record the selected release.

For a submodule, commit the changed themes/devlab-theme pointer in the parent repository. A deployment-only clone should record the tag in its build configuration instead.

Avoid git submodule update --remote: it follows remote branch movement rather than expressing an intentional release selection.

Update a vendored copy

Treat a vendored upgrade as a complete replacement:

Read the release notes and keep the previous project commit available for rollback.
Download the archive for the new tag.
Replace the complete themes/devlab-theme/ directory.
Run zola check and zola build.
Review the resulting diff before committing it.

Do not overlay the new archive on the old directory. Files removed by a release would otherwise remain in the site. Keep site-specific templates, Sass and assets outside the theme directory so replacement cannot erase them.

Roll back

For a Git installation, check out the previous known-good tag and run the checks again:

DEVLAB_VERSION=v0.7.0
git -C themes/devlab-theme checkout --detach "$DEVLAB_VERSION"
zola check
zola build

Then record the restored submodule pointer or deployment version. For a vendored copy, restore the earlier project commit or replace the directory with the previous release archive.

Continue with a real site

The theme is now installed and pinned. Quick start creates a small Home and Docs site; Configuration recipes adds search, Blog, Downloads and branding one capability at a time.