Core capabilities​

• MDX (Markdown + React) as the primary content format.
• Editing with:
  • Local text editors (docs-as-code) with instant rebuilds using the dev server.
  • TinaCMS browser-based rich text editor for non-technical users.
• CCMS-style features (snippets, conditional text, variable sets, taxonomies, glossary terms).

Development workflow​

• Git remains the single source of truth.
• TinaCMS commits directly to Git (or writes files locally).
• Fully compaible with CI/CD pipelines.
• Repository structure closely follows Docusaurus defaults, minimizing surprises.

Preconfigured integrations​

• OpenAPI documentation generation.
• Mermaid diagrams.
• KaTeX math rendering.
• Lunr-based search.
• Internationalization (i18n).

LanguageTool integration is supported for spelling and grammar checking but depends on browser/IDE plugins.

Limitations​

Currently, adopting docStatic implicitly means:

• Owning and extending the platform.
• Accepting limited vendor-style support.

DocStatic is not a good fit for teams who need to produce documentation in print of PDF format. It is not a drop-in replacement for commercial CCMS tools. But, for a large section of the market, it is already functionally equivalent.

Architecture​

Workflow​

DocStatic provides a composable workflow. States are implemented as MDX front matter metadata. The state is read by TinaCMS and rendered through a custom editorial status UI. State transitions are content-native and versioned. This pattern is used by several commercial CCMS vendors. However, enforcement is procedural, not systemic.

Reusable content​

Reusable content is stored in a defined location, managed as independent content and referenced into documents. Snippets are content objects. This closely resembles DITA conrefs.

Translation and localization​

• Locale-specific metadata tracks translation state.
• GitHub Actions:
  • Detect state changes.
  • Trigger Slack or Teams notifications.
• Local previews per locale.
• Translation state is deterministic and can be inspected and automated.

Commercial CCMS offerings include embedded vendor support. DocStatic's approach is translation-ops-as-code. This can be a benefit when implementing automated machine translation, but is less turnkey for non-technical localization teams.

How docStatic compares to CCMS tools​

DocStatic supports:

• Structured content.
• Reusable content objects.
• Workflow states.
• Multi-language support.
• Dashboards (beta).

DocStatic lacks:

• Centralized policy enforcement. Workflow rules live in metadata, Tina UI logic and the CI/CD pipeline.
• Role-based access control. Although this is possible with a paid TinaCloud subscription.
• Migration tooling.

The core difference between docStatic and CCMS tools is composable, inspectable systems against embedded, opaque systems.

DocStatic:

• Prefers explicit metadata.
• Leveraging existing infrastructure (Git, CI, Slack and so on).
• Trades turnkey UX for architectural clarity.

CCMS tools:

• Centralize everything.
• Hide state in the database.
• Optimize for non-technical administrators.

Who is docStatic best for?​

DocStatic can be seen as an engineer-first CCMS. It delivers authoring, reuse, workflows and in-context review—including non-developer feedback directly inside TinaCMS using highlight and comments—while preserving a transparent Git-native source of truth. If you value open tooling, repo-owned workflows and developer-grade extensibility but don't want to sacrifice non-developer review, docStatic could be for you.

Roadmap​

DocStatic narrowly focuses on delivering the best possible online docs experience for readers. Print and PDF are not on the roadmap, and it's unlikely that they ever will be. But there are two areas where using CCMS tools for online docs still has the edge on docStatic:

• Ease of deployment.
• Dashboards.

Dashboards are already in beta. For deployment, the intention is to make it possible to create a default repository using npm.

My solution looked something like this:

• A central documentation repository in GitHub with automated deployments using Actions.
• DAPS for conditional text, translation, customer builds and PDF output.
• Hugo with Asciidoctor for HTML5 sites.
• LanguageTool for spelling, grammar and style checking.
• VS Code with the AsciiDoc and LanguageTool plugins for developers.
• XML Mind XML Editor Web Edition with the LanguageTool browser plugin for non-developers.
• Mermaid for diagrams.
• Pandoc for converting DocBook to Word.
• Affinity Suite for marketing content (imports Word).
• A Lucene derivative for search.
• Matomo for analytics.
• DeepL for machine translation.
• API scripts to publish to wikis (such as Confluence) and knowledgebases (such as Zendesk).

I was the second choice, so fortunately for me I didn't have to deliver it. Instead, I ended up getting a gig where I had to build a documentation portal solution that presented REST and GraphQL APIs in a somewhat consistent manner. That was based on Magidoc, the free Redocly CLI tool, and a lot of scripting. Since then, I've discovered Archbee. It's a Markdown-based system with proprietary extensions for presenting REST and GraphQL APIs. Even if I'd known about it at the time, I don't think I would have chosen it based on documented reliability issues. However, having used it recently for another client, I think it might just be production ready for user docs. It offers a nice web interface, but you can use your own GitHub repository as the source of truth. Changes made in the web editor create pull requests in the repo. It has search and sites can be password protected. It has built-in support for Mermaid diagrams and dark mode. It's quite reasonably priced and because it's Markdown you're not locked in.

But I'm still a fan of DocBook. Was there an off-the-shelf solution that looked more like my hybrid document management system (DMS) proposal? One possible solution would be Magnolia CMS, the Antora static site generator (SSG) and AsciiDoc. However, Magnolia doesn't disclose its pricing. And if you ever wanted to migrate to another system, you'd have to build it yourself because other headless CMS solutions don't support AsciiDoc.

Which lead me back to Markdown. Was there an SSG primarily aimed at producing doc sites that would work with my favorite headless CMS (TinaCMS)? That led me to Docusaurus. It's what Meta (Facebook) built to replace Jekyll as its in-house SSG and it uses React. Its build times can feel like an age compared to Hugo. But the sites it builds are so much faster. But was there a better free REST API docs integration than hacking the output of Redocly CLI? The answer was yes, with a great Docusaurus plugin from Palo Alto Networks. All I should have had to do to set it up was to create a new site using the Tina Docusarus starter and then add the plugin. It wasn't that straightforward. Palo Alto Networks has drunk the TypeScript KoolAid. Because Docusaurus is React, the starter site created by Tina uses JSX. They did not want to play nicely. I ended up creating a site from the Palo Alto Networks template and then grafting Tina support onto it.

I couldn't figure out a way to enable the versioning and localization widgets in the nav bar with the Tina solution, so I reverted to using a fixed definition for those. For most other settings, Tina uses JSON files that are referenced by the config. Adding Mermaid and Lunr search support was trivial, although search only works in production. Rather than try to talk you through everything I had to do to get it working, this time I thought I'd simply share the repo. The Palo Alto Networks component is made available under the MIT license, so I've used the same license. The only config you'll need to do is to add your Tina credentials to enable online web editing.

Going back to the requirements, we've got a GitHub repo with Actions. Docusaurus replaces Hugo as the SSG. We're using Markdown Extended (MDX) in place of AsciiDoc. We can still use LanguageTool with TinaCMS and VScode. We're using Tina in place of the XML Mind editor. We've got Mermaid diagrams, with preview in Tina. We're using Lunr for search, but if that's insufficient, there's built-in Algolia support. There's a plug-in for Matomo analytics. There's a plug-in for GraphQL docs. Docusaurus includes versioning and localization support. We can still use DeepL for machine translation. We can still use Pandoc for print output to PDF or Word for export to Affinity Publisher.