Referencia docs.yaml

.raise/docs.yaml is RaiSE's documentation adapter configuration file. It tells rai docs publish where to send documentation artifacts and how to route each artifact type to the right parent page.

Upgrading from 2.x?

In RaiSE 3.0, confluence.yaml was replaced by docs.yaml. The format is similar but uses default_target: and targets: instead of default_instance: and instances:. See Auto-migration below — you don't need to migrate manually.

For the full upgrade procedure, see the Migration Guide.

File Location¶

.raise/docs.yaml

This file lives at the root of your project's .raise/ directory and is checked into git (shared across the team). It describes what to connect to — credentials (API tokens, usernames) stay in environment variables.

Top-level Fields¶

Field	Type	Default	Description
`default_target`	string	`"default"`	Which target to use when `--target` is not specified
`targets`	map	required	Named documentation targets

Target Fields (`targets.<name>`)¶

Each entry under targets: is a named documentation target. Currently only type: confluence is supported.

Confluence Target¶

Field	Type	Required	Description
`type`	`"confluence"`	yes	Adapter type discriminator
`url`	string	yes	Confluence base URL (e.g. `https://yoursite.atlassian.net/wiki`)
`space_key`	string	yes	Default Confluence space key (e.g. `TEAM`)
`instance_name`	string	no	Instance identifier for token resolution. Default: `"default"`
`username`	string	no	Atlassian account email — usually omitted and read from `CONFLUENCE_USERNAME` env var
`home_page_id`	string	no	Space homepage ID — used as fallback ancestor when a routing entry has no parent page. Provide as a quoted string (`"123456"`)
`routing`	map	no	Artifact type → routing config. Empty map `{}` is valid (uses `home_page_id` as fallback)

Routing Fields (`targets.<name>.routing.<artifact_type>`)¶

Each entry under routing: maps an artifact type (e.g. adr, session-diary) to a Confluence parent page.

Field	Type	Required	Description
`parent_title`	string	yes	Title of the Confluence page to publish under
`labels`	list of strings	no	Labels applied to the page on publish
`local_dir`	string	no	Local base directory for `rai docs write` (filesystem fallback)
`naming`	`"slug"` or `"dated"`	no	File naming convention. `slug` → `{slug}.md`, `dated` → `{YYYY-MM-DD}-{slug}.md`. Default: `"slug"`

Minimal Example¶

One Confluence target, no routing configured. Use home_page_id so rai docs publish has a fallback parent page.

default_target: default
targets:
  default:
    type: confluence
    url: https://myteam.atlassian.net/wiki
    space_key: TEAM
    instance_name: default
    home_page_id: "123456789"
    routing: {}

Full Example¶

Two targets with routing configuration — a main space and a staging space.

default_target: main
targets:
  main:
    type: confluence
    url: https://myteam.atlassian.net/wiki
    space_key: TEAM
    instance_name: main
    home_page_id: "123456789"
    routing:
      adr:
        parent_title: Architecture
        labels: [adr, architecture]
        local_dir: dev/decisions
        naming: slug
      session-diary:
        parent_title: Session Diaries
        labels: [session-diary]
        local_dir: work/sessions
        naming: dated
      epic-docs:
        parent_title: Developer Docs
        labels: [epic-docs]
        local_dir: work/epics
        naming: slug
      roadmap:
        parent_title: Product
        labels: [roadmap]
        local_dir: governance
        naming: slug
  staging:
    type: confluence
    url: https://myteam.atlassian.net/wiki
    space_key: STAGING
    instance_name: main
    routing: {}

Using Multiple Targets¶

The --target flag on rai docs publish overrides default_target for a single command:

# Publish to default target (main)
rai docs publish adr --title "ADR-045"

# Override to staging target
rai docs publish adr --title "ADR-045" --target staging

Auto-migration¶

If your project still has .raise/confluence.yaml, RaiSE migrates it automatically on the first rai docs write call:

RaiSE reads confluence.yaml
Transforms default_instance: → default_target:, instances: → targets:, adds type: confluence to each target
Writes the new docs.yaml to .raise/docs.yaml
Prints: [rai] Migrated .raise/confluence.yaml → .raise/docs.yaml

After migration, commit the new file:

git add .raise/docs.yaml
git commit -m "chore: migrate confluence.yaml to docs.yaml (RaiSE 3.0)"

The old confluence.yaml is still read as a fallback until you remove it. Remove it after confirming docs.yaml works:

git rm .raise/confluence.yaml

Environment Variables¶

API tokens and usernames are never stored in docs.yaml. Set them in your shell:

export CONFLUENCE_API_TOKEN="your-token"
export CONFLUENCE_USERNAME="you@company.com"

Add these to .bashrc or .zshrc for persistence, or use a .env file with direnv.