Skip to content
EkLine
Book a demo

Blog

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

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.

Cover Image for How to keep ReadMe docs in sync with your code and OpenAPI spec
Published on
Read time
9 min

"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.
Diagram: a ReadMe API page split in two; the top half from the OpenAPI spec (parameters, request panel) updates on every re-sync, the hand-written bottom half (guide, recipe example) is kept as is and is the half EkLine keeps current

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:

Native checkWhat it verifiesWhat it does not seeWhere EkLine fits
OpenAPI re-syncSpec-derived parts of each reference page, matched on operationIdYour hand-written Markdown, which it keeps as isAutomatic PR review assesses the API pull request and can start a guide edit
Bi-directional syncThe repository and the hub hold the same pagesWhether a recipe's request still matches the APIDocs Agent opens its pull request in that documentation repository
rdmeFiles in Git reach ReadMe, one wayWhether the files it pushes are still trueDocs Reviewer checks the Markdown in CI, without a ReadMe framework value

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

Part of the workflowWhere it sits
Your Markdown pagesThe GitHub or GitLab repository ReadMe syncs, or the repository your CI runs rdme from.
What EkLine watchesYour API code. The GitHub App separates Code Repositories from Documentation Repositories, and Docs Agent also reviews GitLab merge requests.
Where the Docs Agent pull request landsYour docs repository, on the branch for the ReadMe version it documents.
How the change reaches your hubReadMe's sync, or your rdme step, after your team merges.
CI checkDocs Reviewer checks the Markdown for style, consistency, links, and accuracy. Its framework support page lists no ReadMe value, so it works without ReadMe-specific component handling.
BitbucketDocs Reviewer only, as a Bitbucket Pipelines check.
What stays in ReadMeHosting, the editor, versions, and the reference generated from your spec.

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.

FAQ

No. ReadMe keeps hosting your hub, generating the reference from your spec, and running sync or rdme. EkLine covers the pages ReadMe leaves to you: it reads code changes as pull requests open, sweeps merged work on a schedule, and opens pull requests against your guides and recipes for review. For a side-by-side view, read EkLine vs ReadMe.

Use one for Markdown pages. Bi-directional sync fits a team that edits in both the ReadMe editor and Git, and it needs an empty repository, branch names that match versions, and branch rules that let ReadMe push. rdme fits a team that treats Git as the only source, because it pushes one way.

Partly. Docs Agent works with GitHub and GitLab, so it does not open pull requests in a Bitbucket repository. Docs Reviewer runs as a Bitbucket Pipelines check on your Markdown.

Some teams do. In the Ask HN thread, cyanydeez described "a for loop that runs nightly on any files updated the prior day," handing the Markdown file next to each changed file to local AI to revise. With bi-directional sync, guides start in their own repository, so a recipe has no file beside the API code to pair with. Each rewrite also needs checking, which rstagi called hard: "it's hard to fact-check everything all the time." EkLine starts from the API pull request and drafts guide edits as a pull request in the repository ReadMe syncs, where a person approves them.

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

Read more about
Blog

Cover Image for How to keep Astro Starlight docs accurate after a green build
Blog

How to keep Astro Starlight docs accurate after a green build

·9 min read

A green build tells you the site is well-formed: frontmatter matches its schema, internal links resolve once you add a validator, and API pages render from your spec. It cannot tell you whether a sentence in a how-to is still true, which takes a content check driven by what changed in the product.

Cover Image for How to keep Docusaurus docs in sync with your source code
Blog

How to keep Docusaurus docs in sync with your source code

·9 min read

Docusaurus keeps docs in sync with source code through the repository. It gives you three real sync tools: a monorepo, code blocks imported from files, and a build that fails on broken links.

Cover Image for How to keep Fumadocs docs in sync with your code
Blog

How to keep Fumadocs docs in sync with your code

·9 min read

To keep Fumadocs docs in sync with a Next.js app and its API, let Fumadocs generate every page it can from code (OpenAPI reference pages and TypeScript props tables), then give the hand-written guides around those pages an update loop of their own. A generated page changes when its source changes.

Cover Image for How to keep GitBook in sync with GitHub, and accurate
Blog

How to keep GitBook in sync with GitHub, and accurate

·9 min read

To keep GitBook in sync with GitHub without losing edits, and keep the content accurate, turn on Git Sync, choose the first sync direction on purpose, and edit each page in one place while a change is open. That keeps the editor and your repository identical.

Cover Image for How to keep Mintlify docs up to date when code changes
Blog

How to keep Mintlify docs up to date when code changes

·9 min read

Mintlify already automates the structural half of keeping docs current: it builds API reference pages from your OpenAPI spec, checks links, validates builds, syncs with GitHub, and can draft pull requests when code merges. The half that slips is the prose and the examples whose facts live in other repositories, tickets, and threads.

Cover Image for How to keep VitePress docs in sync with your code
Blog

How to keep VitePress docs in sync with your code

·9 min read

To keep VitePress docs in sync with your code, import every code sample from your source files and leave dead-link checking on, so the build fails when a linked page goes missing and, on the VitePress 2.0 alpha line, when an imported file goes missing. Then review the sentences next to those samples on each release, because no VitePress setting checks that prose against the code.

See what EkLine finds in your docs.

Book a demo

15 minutes to set up. 15 insights of what agents read about you, and 15 days to improve. If you do not see the value, you walk away with 15 better pages.