Route changes to the right doc version

Tip

You can set this up by hand as this page describes, or ask Promptless in Slack or Microsoft Teams to do it for you. For example, “@Promptless set my acme/docs collection default branch to v2 and only trigger on PRs targeting v2.” See Ask Promptless to update your configuration.

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 two ways: each version on its own branch, or all versions in one branch in separate directories. Promptless works with both — this page shows how to route changes under each model, and how to steer directory-based routing with your Knowledge Base.

Versions on separate branches

When each version lives on its own branch, point a doc collection at the branch a version lives on and scope your triggers to the branches you care about. Promptless then targets the right base branch automatically.

On the Doc collections tab, select the doc collection and expand More filters (optional). The Default branch setting controls which branch Promptless targets for its pull requests. It defaults to the repository’s default branch, so set it to the branch where a version’s documentation lives. (In your promptless.yaml this is the default_branch field — see the Configuration Reference for the full doc-collection schema.)

On the Triggers tab, open a GitHub pull requests trigger and expand More filters (optional). Add the Only pull requests targeting these branches rule and list the version branches you want, so a change to one version doesn’t start documentation work for another. A GitHub commits trigger offers the same choice through its Which branches? field. Leave it empty to watch just the default branch. (These map to the per-trigger branches field in promptless.yaml, documented in the Configuration Reference.)

Base branch targeting is automatic. When a change comes from a non-default branch, Promptless opens the suggestion against that branch rather than the default. That’s exactly what you want when a change lands on a version branch. Open suggestion branches stay synced with their base branch while open, so a suggestion always builds on the latest documentation state.

Versions in separate directories

Some frameworks, like Docusaurus and Starlight, keep every version in one branch and split them into directories. Under this model, routing is about which directory a change lands in, not which branch.

Use the collection’s path scope to limit where Promptless works. On the Doc collections tab, expand More filters (optional) and set Only watch these folders (filter in promptless.yaml). It limits which files and folders Promptless may modify and accepts any directory prefix, so you can scope Promptless to a single version directory like versioned_docs/version-2.0/, or to several. Note that it is include-only. There is no exclude or deny list, so “pointing away from” a directory means listing the directories you do want. See the Configuration Reference for the doc-collection schema.

On the source side, the Only when files in these folders change trigger filter (trigger_directories) controls which directories must change to start documentation work. It filters where the change happened, not where Promptless writes. It does not choose the destination version directory.

There is no configuration field that maps a source change to a specific target version directory. Within one collection, which version directory Promptless edits is relevance-based: it reasons from the change and its context, and you steer it with path scope (above) and Knowledge Base instructions (see the next section). Version-directory targeting isn’t automatic the way branch base-targeting is. Because each suggestion is a proposed change you review before merging, you can confirm it landed in the right version directory from the suggestion’s file changes before approving it.

Each repository can have at most one doc collection, so you can’t create a separate collection per version directory. All of a repo’s version directories share one collection. (That’s why steering it matters.) If your versions are spread across repositories instead, see Route changes across multiple repos.

Steer version routing in your Knowledge Base

Because directory targeting is relevance-based, your lever is PROMPTLESS.md in your Agent Knowledge Base. Tell it 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 in docs/. Older versions in versioned_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/ and versioned_docs/version-2.0/ and note the LTS edit in the suggestion.”

Note

Promptless has no dedicated “version” concept and models versions as the branches or directories your docs already live in. For separate branches, base-branch routing is automatic. For separate directories, targeting is relevance-based, so limit it with path scope and steer it with Knowledge Base instructions.