How to keep ReadMe docs in sync with your code and OpenAPI spec

"How do I keep ReadMe docs in sync with my code and my OpenAPI spec?" ReadMe handles half of that job. When you re-sync an OpenAPI file, ReadMe updates the spec-derived parts of each API page in place and leaves the Markdown you wrote alone. Your guides, recipes, and examples are that Markdown, so they need an update path of their own.

Follow one change: your API adds a new required request parameter. You run rdme openapi upload, and the reference page for that operation shows the parameter in an updated request panel. The getting-started guide and the recipe that call the same endpoint still show a request without it.

TL;DR

• When you re-sync the spec, ReadMe updates the reference pages and keeps your hand-written Markdown exactly as you left it.
• Use bi-directional sync or rdme for Markdown, never both, and keep every operationId stable.
• Guides, recipes, and samples need a review step tied to code changes, which EkLine adds from GitHub or GitLab.

What ReadMe keeps current when you re-sync

Bi-directional sync connects your project to "a GitHub, GitLab, or Bitbucket repository so content stays in step whether you edit in ReadMe or in your repo," and "All content types sync, including guides, API reference pages, custom pages, recipes, and changelogs." The repository "must be empty" before you connect it, with "no commits or files," so it cannot be your existing API codebase. Your code and your docs end up in separate repositories.

rdme is "ReadMe's official command-line interface (CLI) and GitHub Action," and it "pushes one way, from your files to ReadMe, so edits made in the ReadMe editor don't flow back to your repository."

ReadMe matches pages on operationId and "updates the existing API Reference pages in place rather than creating a second set." "The parts of the page that come from the document, such as the summary, parameters, and request and response panels, update to match the new definition." The new required parameter appears on the reference page with no edit from you.

Where hand-written ReadMe pages drift

Test it on your own hub. Open the last merged pull request that added or changed a request parameter. Did anything flag the guide or recipe that calls that endpoint? Each native tool did its own job:

The same re-sync page says your Markdown "is kept through every kind of re-sync." That protects your writing, and it also means no ReadMe process updates it. Three places still hold the old request:

• The getting-started guide that walks a reader through a first call.
• The recipe for that endpoint.
• Any prose or sample you added to the reference page itself, now sitting beside refreshed panels.

Third-party sync glue brings failure modes of its own. In May 2026, JohnRDOrazio found his project's old github-readme-sync action "no longer maintained" and filed "Replace broken ReadMe.io sync workflow with self-hosted docs (OntoKit pattern)." davidt99 reported that "Docs upload format are incompatible with bi-directional sync"; ReadMe closed it as not fixable. An operationId change is worse than a rename: to ReadMe, "a changed ID is a deleted endpoint plus a new one. The old page, its URL, and any edits made to it are removed."

Does the GitHub AI Writer close the gap?

For some teams, yes. ReadMe's GitHub AI Writer "Proposes documentation updates when pull requests change your codebase." When a pull request opens in a connected repository, it "analyzes the diff, identifies new endpoints that need documentation or setup steps that have changed, and drafts the update on a review branch in ReadMe." It is "Available on Pro plans and above." If your API code is on GitHub and the pull request holds everything the guide needs, it covers the example change.

Its docs describe only a GitHub integration, so GitLab code has no documented path. Its docs describe it reading the diff and describe no input from tickets, Slack threads, or specs. It starts when a pull request opens, so work that merged before you connected it waits for someone to notice.

When is ReadMe's tooling enough on its own? When the guide edit can ride in the same pull request as the code and that pull request carries every fact, as with Markdown kept beside the code and pushed by rdme. Bi-directional sync needs an empty repository when you connect it, so in practice the guides start in a repository of their own. Once facts sit there, or in a ticket, a Slack thread, or a spec, the same-PR rule leans on memory; commenters in an Ask HN thread on the topic rely on docs-first rules and nightly scripts.

A ReadMe sync checklist for this week

• Pick one path for Markdown pages. ReadMe says "If your project has Bi-Directional Sync enabled, you don't need rdme," though you still need the CLI for OpenAPI files.
• Check every synced branch's rules: "your Git provider can reject the commits ReadMe pushes to it" when protection rules or rulesets apply.
• Name branches exactly after your ReadMe versions, as ReadMe requires, so the branch a change merges into is the version it updates.
• Give every operation an explicit, stable operationId, because a generated ID changes with the path and takes the old page with it.
• When the spec changes, search your guides, recipes, and reference-page prose for the changed operation before you close the release.

How EkLine plugs into a ReadMe setup

An engineer opens a pull request in the API repository that adds the required parameter. Automatic PR review assesses its diff, title, and description once, when it opens. A high-confidence result starts a docs pull request editing existing pages such as the guide and the recipe; a medium result posts a suggestion comment. You merge it, ReadMe's sync or your rdme step carries the guide to the hub, and the reference updates from the spec. If the review stayed silent, the weekly Docs Drift Review audits the last 30 days of GitHub activity. When the parameter came from a ticket or spec, a Docs Agent session can combine that source with the pull request. Code Sample Review "Verifies that code samples in your docs are accurate and runnable."

Can one writer keep pace with a busy API? At Socure, an identity intelligence company, one technical writer merged 348 documentation updates in seven weeks with no added headcount. The case study does not say which docs platform Socure uses.

If you are weighing a self-hosted move, Potluck Docs, EkLine's open-source Astro and Starlight template, renders OpenAPI references with Scalar and a built-in client for sending real requests.

---

Take the last pull request that added a parameter to your API, and bring it to the call. To see what Docs Agent would change in your ReadMe guides after your next spec update, book a demo. Docs Agent is available to all plans, with access granted on request.

Sources

• ReadMe: OpenAPI re-syncing
• ReadMe: Bi-Directional Sync
• rdme on GitHub
• ReadMe: rdme
• ReadMe: GitHub AI Writer
• JohnRDOrazio: Replace broken ReadMe.io sync workflow with self-hosted docs (OntoKit pattern)
• davidt99: Docs upload format are incompatible with bi-directional sync
• Ask HN: How do you keep documentation up to date with AI generated code?
• EkLine: GitHub App setup
• EkLine: Changelog
• EkLine: Documentation framework support
• EkLine: Bitbucket integration
• EkLine: Automatic PR review
• EkLine: Prevent documentation drift
• EkLine: Combine sources
• EkLine: Scheduled Agents
• EkLine: Socure case study
• Potluck Docs
• EkLine vs ReadMe