Docs as code workflow: the same review gate for your blog

A docs as code workflow isn't a metaphor. It's a named practice, plain text files, version control, pull request review, and an automated pipeline, that technical writing and DevRel teams have run for years to keep documentation trustworthy. Most marketing blogs have never adopted that workflow, even the ones that already store their posts as Markdown files in a Git-based blog. This post names the practice, shows what carries over to blog content unchanged, and where the one real gap sits.

What does a docs as code workflow mean? Markdown, Git, PR review, and CI/CD

Docs as code is the practice of writing documentation with the same tools and workflow as software: plain text markup, version control in Git, code-review-style pull requests, and automated build and test pipelines (Write the Docs). Write the Docs lists the specific pieces: issue trackers, Git, Markdown or reStructuredText or AsciiDoc, code reviews, and automated tests. None of that is exotic. It's the exact toolchain most engineering teams already run for the product itself, pointed at the words that describe the product instead.

The mechanic that makes it work isn't the file format. It's the gate. Write the Docs describes teams blocking a feature's merge until its documentation is included, which incentivizes writing docs while the feature is still fresh in the author's head. Fern's docs as code guide states the same rule from the other direction: "When you update an API endpoint, you update the documentation in the same pull request. When code gets reviewed, docs get reviewed" (Fern). Docs and code move through the identical checkpoint, so neither one can drift ahead of the other unreviewed.

That's the part worth separating out before anything else: docs as code is not "Markdown files live in a folder." A pile of .md files with no PR, no required check, and no merge rule is just files in a folder. Docs as code is the review gate wrapped around those files, and the gate is what a blog can borrow wholesale.

Why technical writing teams adopted a docs as code workflow, and most marketing blogs never did

Technical writing teams didn't adopt docs as code for the file format. They adopted it to fix an ownership problem that a CMS makes worse, not better. Squarespace's Domains engineering team documented this directly when they moved their internal docs into what they call Continuous Documentation: "Traditional tools default to the author owning the doc, which is known to cause friction or information loss when members switch teams" (Squarespace Engineering). A doc with one named owner in a separate tool dies the day that person changes roles. A doc in a repo, reviewable by anyone with access, doesn't.

Rafael Peixinho, the team's Engineering Team Manager, put the reasoning in one line: "Less friction leads to more collaboration and, ultimately, better communication within and beyond our team" (Squarespace Engineering). His team's rule for what belongs in the repo is just as direct: "If it's technical, it belongs in our repos where anyone can find it and propose edits as needed" (same source). Mintlify's docs as code guide backs the same mechanism from the contributor's side: developers are more likely to actually write documentation when it doesn't require leaving the tools they already use, since "they can track changes, submit pull requests, and use automated build processes" without switching context (Mintlify).

None of that reasoning is specific to API references. A blog has the identical ownership problem, one writer sitting on a Google Doc nobody else can propose a change to, and the identical fix, a repo anyone with access can open a PR against. Marketing blogs mostly never made the jump anyway, and the tooling data shows why: only 21% of documentation teams publish through an open-source platform or Git repo, against 45% on a dedicated documentation tool and 9% on a general website publishing platform, per the State of Docs Report 2026's survey of 1,131 documentation professionals (State of Docs 2026). Git-based publishing is a minority pattern even inside docs, where the practice originated. Blogs, which mostly grew up on WordPress and dedicated CMS platforms with no version control at all, had even less reason to bump into it.

Applying the same workflow to blog content: what changes, what doesn't

Move docs as code from a docs repo to a blog repo and most of the machinery doesn't change at all. What changes is upstream of the workflow: what triggers a post, not how the post gets reviewed.

What changes: keyword research, editorial calendars, and voice replace API specs and release notes

A documentation PR usually exists because a feature shipped. A blog PR exists because a topic scored well in keyword research, a competitor left a content gap, or an editorial calendar slot came due. The trigger is different, and so is the standard the content gets held to: a docs reviewer is checking technical accuracy against the code; a blog reviewer is checking search intent, brand voice, and whether the piece actually says something a reader needed. Those are real, substantive differences, and no amount of workflow tooling erases them. This is also where the content itself starts to diverge structurally, our post on static site generators for SEO covers how a blog's rendering and metadata needs differ from a docs site's even when both run through the same kind of pipeline.

What stays identical: Markdown files, a Git branch, a pull request, and CI checks before merge

Strip the trigger away and the mechanics are the same four pieces in the same order: a Markdown file with frontmatter, a feature branch, a pull request that shows the change as a diff, and automated checks that have to pass before a human can merge. A blog post's frontmatter (title, excerpt, date, tags) plays the same role a docs page's front matter does, structured metadata the build reads to place the file correctly. The PR is still the one surface where every stakeholder, technical or not, looks at the same diff and either approves it or doesn't.

CI is where a blog workflow gets to reuse docs as code thinking almost line for line. A documentation pipeline runs link checks, build validation, and style linting before a PR can merge. A blog pipeline can run the equivalent: a broken-link scan across the Markdown, a build step confirming the post actually compiles into the site, and checks on meta tags, canonical URLs, and structured data. We cover exactly that pipeline, four specific GitHub Actions jobs and how to wire them into a required check, in GitHub Actions for blog SEO. None of those checks judge whether the writing is good. They catch what a tired reviewer skims past, and that's precisely the job CI already does for code.

This exact post is that pipeline, not a description of it. It lives at content/blog/docs-as-code-workflow-for-blogs.md, a single Markdown file with the frontmatter block above, added on a branch and opened as a pull request against this repo. A companion entry in this repo's sitemap-lastmod-overrides.json has to change in the same commit, or the page never gets flagged for recrawl. Merging to main is what triggers the build and, through a GitHub Actions job, an IndexNow submission of the new URL to search engines that support it. No one edited a database row or clicked publish in a CMS to make that happen. The post exists because the file, the branch, and the required checks lined up, the same discipline this piece is describing.

The one gap docs as code inherits: a marketer who can't read a Markdown diff

The State of Docs Report 2026 surveyed 1,131 professionals, more than 2.5x the prior year's sample, and found only 35% identify as technical writers by title. The other 65% span leadership and decision-makers (21%), engineers (15%), customer experience (7%), operations (6%), support (5%), DevRel (5%), and marketing (4%) (State of Docs 2026). Even inside documentation, most people touching the workflow aren't writers by trade. A blog's reviewer pool skews further from engineering than that: the person who has to sign off on a post is usually a marketer, a founder, or a subject-matter expert, not someone who reads diffs for a living.

That gap is documented, not hypothetical. A docs as code review guide names the exact routing-around pattern: facing a raw Markdown diff, non-technical reviewers tend to "ignore the PR entirely," leave "vague comments like 'looks fine,'" ask the writer to "copy the content into Google Docs for review," or "send feedback via email or Slack, outside the PR" (Draftview). That's not a lazy reviewer. It's a reasonable person declining to review markup they weren't trained to read, and going back to the tool they trust. We go deeper on that exact failure mode, and the fix, in Slack vs GitHub PR for content approval.

The fix docs as code teams converged on for this same problem, long before blogs adopted the practice, is a rendered preview attached to the PR: a URL the reviewer can click that shows the finished page, not the markup underneath it. Approve the rendered preview, and the merge still goes through the same PR, the same required checks, the same audit trail. Nothing about the gate weakens; the diff just stops being the only view a non-technical reviewer is offered. Our post on preview deployments for AI blog content walks through wiring that up on Vercel and Netlify.

Docs tooling itself grew out of the same instinct: platforms built to render Markdown as a real site rather than leave contributors staring at raw source. Docusaurus and GitBook took that further than most, and our breakdown of Docusaurus and GitBook for SEO covers where that rendered-preview convenience ends and a real content workflow still has to pick up the review discipline.

Where this hands off to an AI drafting step without giving up the review gate

Docs as code was never about who writes the file. It's about what happens after: a branch, a PR, CI checks, a human merge. That framing makes an AI-written blog post a non-event for the workflow, not an exception to it. An AI draft is just another PR author. It opens a branch, commits a Markdown file with the right frontmatter, and waits in the same queue as a post written by a person.

That distinction matters because it's also where a docs as code blog can quietly break. The gate isn't the file format or the fact that a repo exists, it's the requirement that a human reads the diff (or the preview) and approves it before anything ships. An AI writer that auto-publishes straight to a CMS skips that requirement entirely, and a Markdown file in a repo that nobody actually reviews before merge does the same thing with extra steps. Our post on a Git-based AI blog writer covers what to look for in a tool built for this slot specifically: one that opens a pull request and stops there, never one that publishes on its own.

That's the seam Lyra sits in. She drafts a post as a Markdown file that matches your existing frontmatter, fact-checks every claim against a current source, and opens a pull request with you tagged to merge, on a branch that can't touch production until you approve it. The workflow doesn't change to accommodate her. She just becomes the next PR author in a process your team may already be running for its docs.

If your docs already run on this workflow, a Markdown file, a branch, a pull request, and CI before merge, your blog can run on the identical one, with an AI draft as just another PR author, never a shortcut around review.

Try Lyra → · Talk to the founder