specgit vs GitBook

Where the content lives

In GitBook you author inside a GitBook space. Turn on Git Sync and that space mirrors with a GitHub or GitLab repository in both directions: edits in the GitBook editor land in the repo as commits, and commits pushed to the repo show up in GitBook. Sync is available on every plan including the free one, though only admins and creators can configure it.

In specgit there is no second home. You open a file that already exists in your repository, edit it, and the save writes to that file as a commit under your own GitHub identity. specgit never keeps a copy of your documents or comments, and GitHub remains the source of truth.

Git Sync does leave real Markdown in your repo, which answers most of the lock-in worry. What remains is a difference of direction. In GitBook the docs are made in the platform and the repo is a mirror you opted into; with specgit the repo is the only place they have ever been. That matters when the file is a spec engineers and AI coding agents read next to the code.

How a change gets reviewed

GitBook has its own review flow. You open a change request, teammates comment and approve inside GitBook, and when the space is synced you can also control who may push live by setting merge permissions on the Git side. Review happens where the writing happens, which suits a docs team that owns its publishing.

specgit puts review in the pull request, and that inheritance is the strongest thing on this page. Highlighting a paragraph and commenting starts a real PR review thread an engineer can answer from GitHub without opening specgit. Publishing is a merge, so whatever your repo enforces is what happens: if a ruleset requires two approvals, specgit shows one of two and blocks the publish until the second lands. Authors request reviewers from the publish menu, reviewers approve or request changes under their own GitHub identity, and Publish when approved merges the moment the last approval arrives. Commits carry their author's name, the history stays complete, and the pull request CI your repo already runs, including link checkers, linters, and site builds, checks the doc change too.

Every one of those controls already exists in an engineering org, already has an owner, and is already trusted. Choosing a platform's built-in review means configuring a second permissions and approval system and asking it to model the one you run for code. specgit uses the real one and puts a visual editor in front of it, so PMs, designers, and support teammates take part without a GitHub tab open. Teams whose reviewers are all writers, with no engineering review culture to inherit, will find GitBook's change requests more comfortable.

Editing for people who do not write code

GitBook's editor is block based and pleasant to use, with custom blocks and structured page hierarchies. A support lead or a PM can be productive in it on day one without seeing Markdown.

specgit's editor points at a file in your repo. Nobody types Markdown, but what gets written is Markdown, and the flavor is broad: wiki links and embeds, callouts with custom titles and fold markers, highlights, footnotes, KaTeX math, YAML frontmatter, task lists, and inline Mermaid diagrams. Syntax specgit does not recognize survives byte for byte on save, so an editing pass does not quietly rewrite someone else's file.

The rest follows from these being repo files: live co-editing, a redline View changes diff against main with selective undo, conflict resolution in the editor, and importing Word, PowerPoint, Excel, or PDF files by converting them to Markdown. That migration path is covered here.

Publishing and hosted docs sites

GitBook renders and hosts the site. You get a documentation website with navigation, search, and a custom domain without running a build or picking a theme, and for a public manual that bundle is hard to argue with.

specgit is not the renderer, though it does trigger the publish. Publishing merges to the base branch, which in a docs-as-code repo is the event that ships the site: a build wired to GitHub Pages, Docusaurus, MkDocs, Vercel, or Netlify fires on that merge exactly as it fires on an engineer's. What specgit leaves to the pipeline is the reader-facing layer, meaning themes, a custom domain, and site search.

With no pipeline today and no appetite for setting one up, GitBook gets you a live site faster because the hosting comes bundled. With a pipeline already running, or a willingness to add a standard one, specgit is the editing and review layer in front of it: one copy of the content, no per-site platform cost, and the site updating on every merge.

AI features

GitBook bundles AI into its plans rather than selling it separately, including an assistant and an agent reachable from tools like Slack, Linear, and GitHub. It is aimed largely at readers of your published docs and at authoring inside the platform.

specgit AI has three modes inside the editor, plus voice. Agent chat co-edits with you, Review posts inline comment threads on the draft like a human reviewer would, and Triage works through the open comments. Two rules apply throughout: AI runs only when a person invokes it, and every proposed change needs human approval before it is applied or posted. Routine usage records hold metadata rather than content, and the model provider runs with Zero Data Retention, so inputs and outputs are not persisted or used for training.

The Free plan includes one AI Review and one AI Triage run a month, which is enough to judge the output. Paid plans meter usage in dollars at published rates, with on-demand usage off by default until an admin enables it with a limit.

How the pricing is shaped

The two products bill on different axes, which matters more than any single number. GitBook charges per published site plus a per-user fee, so cost tracks how many sites you run and how many people are in the workspace, and its free plan is scoped to a single user. Current figures are on GitBook's pricing page.

specgit charges per editing seat, and only editors count, so a reviewer who never types is never a seat. The Free plan covers unlimited collaborators on one repository with five publishes a month. Paid plans lift the repo and publish limits and add the AI co-editor; the breakdown is on pricing.

A rough rule: several distinct doc sites for a handful of people favors GitBook's shape, and a lot of people touching internal docs in one repository favors specgit's.

Privacy and who holds a copy

GitBook is a hosted platform, so your content is resident there whether or not you sync it to a repo. For a public documentation site that is exactly the arrangement you want, and Enterprise plans add controls like IP allowlisting for Git Sync.

specgit is built the other way round. Zero Content Retention means specgit never keeps a copy of your documents or comments. The only things that touch specgit servers are temporary: live collaboration state while people edit together, AI you explicitly invoke, and a transcript if you choose to share one as feedback. Product analytics are content free and never receive documents, comments, prompts, repo names, or paths. Mechanics are on security, architecture on how it works. If your specs describe unannounced products, this is usually the criterion that decides it.

The comparison at a glance

The table runs both tools through the same criteria in the same columns.

Pick GitBook if

GitBook is the right answer more often than a page on our own site might suggest.

• You want a public docs site with search and a custom domain, and you would rather buy the hosting than run a build pipeline for it.
• A docs team owns the content and reviews its own changes rather than handing them to engineers.
• You publish for customers, and the reading experience is part of the product.
• You want AI aimed at readers of the published docs as well as authors.
• Your content is not sensitive enough that a platform holding a copy is a problem.

Pick specgit if

specgit is narrow on purpose. It is the editor and the review layer over files you already own, and it hands rendering to whatever your repo already uses.

• The docs are internal specs, decision records, or engineering documentation that belongs next to the code.
• The files should stay plain Markdown in a repository you control, with no platform holding a copy.
• Doc changes deserve the review apparatus your org already trusts: required approvals, branch protection and rulesets, reviewer assignment, per-line threads, attributed history, and the CI the repo runs.
• Your repo already builds a docs site on merge, and you want the writing and the review to sit in front of that pipeline rather than inside a platform that keeps a second copy.
• PMs, designers, and support teammates need to edit without learning Git or Markdown. The full workflow is here.
• Your docs folder uses Obsidian-flavored Markdown and wiki links, callouts, and embeds must survive an edit. More on that setup.
• AI coding agents in your repo should be reading the current spec, since they only see what is in the repository.

Frequently asked questions