Publishing & Releasing Docs

This guide explains how to release documentation changes and keep the VitePress website updated.

Pushing Changes to Repository Docs

Most board firmware and backend repositories hold their own documentation within their respective folders (for example, under repos/CAN-Gateway/docs/ or repos/Galvanic-Isolator/docs/).

To publish updates to the live site:

1. Commit and Push: Commit your changes to the board's repository.
2. Push a Version Tag: Push a new tag to the repository. The webserver automatically detects the tag, pulls the latest contents, and updates the website.
   • For documentation updates, follow the team convention: increment the last digit (minor/patch version) of the version tag (for example, if the current version is v1.2.1, release the next documentation update as v1.2.2).

Modifying the Documentation Repository

When you edit or add files directly in the main documentation repository (like configuration or global pages):

1. Commit your modifications to the documentation repository.
2. Update the Submodule Index: Since board-level repositories are tracked as submodules under the repos/ folder, you must also update the submodule references in the documentation repository if any commits were pushed to the submodule repos.
   • This ensures the website always pulls the correct tag/commit for each submodule, avoiding situations where documentation becomes outdated or desynchronized by mistake.

WARNING

Always verify that your submodule references point to the latest released tag before committing your changes in the main documentation repository.

Local Verification

Before pushing, it is a best practice to verify your changes locally:

1. Run the build command in the root folder of the documentation repository:

   npm run docs:build

2. Check that the build completes successfully and no broken relative links are reported.