Integrate into Your Workflow

As documentation scales, it requires the same rigor as product development. Without a defined workflow, content quickly falls out of sync with releases.

This guide documents the standard documentation workflows used by teams integrating ReadMe into CI/CD pipelines. These workflows are designed to:

Keep documentation versioned with releases
Enforce clear ownership and review processes
Scale across teams, products, and content

If you’re setting this up for the first time, follow the recommended workflow below. It reflects how most organizations successfully operate at scale.

Workflow Patterns

Branching

Structured review for documentation updates

Docs-as-Code

Docs as Code with CI/CD publishing

Hybrid

Split ownership across teams and tooling

ReadMe's MCP Server

Update docs from your AI coding assistant or CI pipeline

Key Terms

These are building blocks shared across all setups:

ReadMe CLI (@readme/cli): Lints pages, validates OpenAPI definitions, and keeps API Reference pages in step with them in a repository connected with Bi-Directional Sync. See ReadMe CLI.
rdme Upload CLI (rdme): Automates OpenAPI validation, uploads, and documentation updates from CI/CD pipelines. See rdme Upload CLI.
Git, GitHub, GitLab: Acts as the source of truth for OpenAPI specifications and Markdown documentation (optional).
CI/CD (GitHub Actions, GitLab CI, etc): Runs validation, linting, and publishing steps on pull requests and merges.
Bi-Directional Sync: Keeps content aligned when edits happen in both Git and the ReadMe Editor.

FAQ

What does a synced repository look like?

With Bi-Directional Sync, the folder names are set by ReadMe, one top-level folder per type of content: docs, reference, recipes, custom_pages, custom_blocks, and changelogs. Your OpenAPI files live at the top level of reference/, so there's no separate openapi folder.

See Documentation Structure for the full layout, sidebar ordering, and frontmatter.

What if I use rdme instead of syncing?

Then the folder names are up to you. rdme uploads whatever file or folder you point it at, such as rdme openapi upload openapi.yaml, so you can organize your repository however suits your team.