Route changes to the right doc version
Overview
Section titled “Overview”Teams that run more than one live version of their documentation need each change to reach the version it belongs to. Teams commonly version docs in one of two ways: each version on its own branch, or every version in its own directory on one branch. Promptless works with both, and models versions as the branches or directories your docs already use. This guide shows how to route changes under each model, and how to steer directory-based routing with your Knowledge Base.
Before you start
Section titled “Before you start”- An admin role in your Promptless organization, to edit the Configuration page and the Agent Knowledge Base.
- Your docs repository connected as a doc collection. See GitHub repos.
Route versions on separate branches
Section titled “Route versions on separate branches”When each version lives on its own branch, point the doc collection at a version branch. Then scope your triggers to the version branches you care about:
-
On the Doc collections tab of the Configuration page, expand the doc collection, then expand More filters (optional).
-
Set Default branch to the branch where a version’s documentation lives. Promptless opens its pull requests against this branch. Without it, Promptless targets the repository’s default branch.
-
Select Save changes.
-
On the Triggers tab, open a GitHub pull requests trigger and expand More filters (optional).
-
In Only pull requests targeting these branches, list the version branches to watch. A change to one version then starts no documentation work for another. For a GitHub commits trigger, list the branches in Which branches? instead. Left empty, Which branches? watches only the default branch.
-
Select Save changes.
In promptless.yaml, these settings are the doc collection’s default_branch field and the trigger’s branches field. See the configuration reference.
When a change comes from a non-default branch, Promptless opens the suggestion against the branch the change came from. A change that lands on a version branch updates that version’s docs. While a suggestion is open, Promptless keeps its branch synced with its base branch, so the suggestion builds on the latest documentation.
If a suggestion’s pull request targets the wrong version branch, change its base branch on GitHub or GitLab. Promptless moves the suggestion to your branch the next time it updates the suggestion, such as after you request changes. Promptless keeps the earlier base if it can’t find your branch. It also keeps the earlier base if, on your branch, the changes reach outside the collection’s Only watch these folders scope.
Route versions in separate directories
Section titled “Route versions in separate directories”Some frameworks, such as Docusaurus and Starlight, keep every version on one branch, each in its own directory. Under this model, routing decides which directory a change lands in.
Within one collection, Promptless picks the version directory to edit by relevance, reasoning from the change and its context. No configuration field maps a source change to a target version directory. Each repository can have at most one doc collection, so all of a repository’s version directories share one collection. If your versions live in separate repositories instead, see Route changes across multiple repos.
You steer directory targeting with path scope and with Knowledge Base instructions. To limit which version directories Promptless can modify:
-
On the Doc collections tab of the Configuration page, expand the doc collection, then expand More filters (optional).
-
In Only watch these folders, list each directory Promptless may modify, such as
versioned_docs/version-2.0/. Path scope is include-only, so to keep Promptless out of a directory, list only the directories you want it to change. -
Select Save changes.
In promptless.yaml, path scope is the doc collection’s filter field. See Path scope.
The Only when files in these folders change trigger filter (trigger_directories) works on the source side. It sets which directories must change to start documentation work, and it doesn’t choose the destination version directory.
Before you approve a suggestion, check its file changes to confirm it landed in the right version directory.
Steer version routing in your Knowledge Base
Section titled “Steer version routing in your Knowledge Base”Because directory targeting is relevance-based, PROMPTLESS.md in your Agent Knowledge Base is your main lever. Tell Promptless which directory holds the current version and which directories hold frozen releases, so it edits the right one. For example:
- “In
acme/docs, the current version lives indocs/. Older versions inversioned_docs/are frozen. Leave them alone unless I say otherwise.” - “Apply changes to the latest version directory,
versioned_docs/version-3.0/. Don’t touch released version directories.” - “When both the current and a supported LTS version are affected, update
docs/andversioned_docs/version-2.0/and note the LTS edit in the suggestion.”
For the steps to edit PROMPTLESS.md, see Set per-collection preferences in your Knowledge Base.
See also
Section titled “See also”- Route changes across multiple repos, to route changes when your versions or teams span several repositories
- Configuration reference, for the full doc collection and trigger schema
- Build an agent knowledge base, to write and organize Knowledge Base instructions