hermesbaby 2026.3.2.51

The Software and Systems Engineers' Typewriter

HermesBaby

The Software and Systems Engineers' Typewriter

Meant to be the authoring environment to get our work done.

Purpose

Using HermesBaby to Enable Docs-as-Code in Corporate Environments

HermesBaby provides a curated toolbox and clean command-line interface that operationalizes the Docs-as-Code approach across engineering organizations. It is designed to simplify both the authoring experience for engineers and the integration into corporate environments — including CI/CD, documentation portals, and internal security policies.

For document authors, HermesBaby makes Docs-as-Code accessible:

• Projects are scaffolded from templates in seconds.
• Authoring happens in the same environment used for code development.
• Build, preview, and publish commands are cleanly separated and easy to use.
• Kconfig-based configuration offers clarity and traceability without clutter.

At the same time, HermesBaby is built for integration at scale:

• It works seamlessly with CI pipelines and version-controlled repositories.
• It supports custom toolchains and validates external dependencies automatically.
• It installs and configures required build tools, linters, and extensions — even in headless or air-gapped environments.
• It ensures predictable and compliant deployments via SSH-based publishing and access control via .htaccess.

HermesBaby doesn't just promote structured authoring — it makes documentation controllable, auditable, and cyber-secure. Its infrastructure-aware design allows teams to:

• Verify toolchains before use.
• Lock down deployment keys and paths.
• Comply with internal policies and regulatory requirements.

By lowering the barrier to entry for engineers while raising the bar on control and compliance, HermesBaby bridges the cultural and technical gap between grassroots Docs-as-Code practices and enterprise-grade documentation workflows.

See also: «Article» Engineering Mechatronic Product Lines using the Docs-as-Code Approach

Installation

While it's possible to install it globally via pip, it's recommended to install it via uv tool to keep your system clean and tidy since hermesbaby brings many Python packages with it.

python3 -m pip install uv
uv tool update-shell

uv tool install hermesbaby

Using pipx is common as well :

python3 -m pip install pipx
pipx ensurepath

python3 -m pipx install hermesbaby

You update it later via:

uv tool update hermesbaby

respectively, in case you work with pipx:

python3 -m pipx upgrade hermesbaby

First usage

Close the gaps by installing the missing tools. You may use the help hermesbaby gave you to do so.

Beside hermesbaby there is a second, shorter alias:

hb

Check environment for prerequisites

hb tools check

Start your first new virtual piece of writing

hb new --list-templates
hb new --template hello some_dir
cd some_dir
hb html-live

CTRL-C.

Start editing

git init .
code .

Click Statusbar / html-live

Apply changes to some docs/*/index.md ... and so on.

Happy coding specifications ;-) "

Development and Testing

Running End-to-End (E2E) Tests

The E2E tests are written using BATS. To run them manually, ensure you have the project dependencies installed via Poetry.

# Enable the virtual environment:
poetry install --with dev
# Set up the development environment after you have cloned the repository:
# a) Windows (in git-bash):
source ./.venv/Scripts/activate
# b) Linux / macOS:
# source ./.venv/bin/activate

# Enter the TDD-Loop:
# 1) Run not all tests but the tests focussing on the feature you want to implement, e.g. for bibliographies:
tests/e2e/bats/bin/bats tests/e2e/test-bibliographies.bats -x --show-output-of-passing-tests
# 2) edit your files
code .
# Go to 1) and repeat until you are happy with the implementation.

# After the 2nd run, you can compare the outputs with using Beyond Compare:
bcomp tests/data/bibliographies/out_1 tests/data/bibliographies/out &

# After you are done, you can run all tests to check if everything is fine:
tests/e2e/bats/bin/bats tests/e2e/ -x