# Doctave - Build beautiful developer portals with docs-as-code Build beautiful developer portals with docs-as-code. Write, publish, and collaborate technical documentation using a Git-based workflow. This is one page of public article previews, not the complete archive. Follow Next page to continue. Summaries are not the original full articles. ## Doctave is shutting down DevFeed: [Doctave is shutting down]() Original publisher: [Read original article]() Author: Niklas Begley Published: 2026-08-31T06:00:00Z Content type: release Language: en Sources: [Doctave - Build beautiful developer portals with docs-as-code]() Topics: [Documentation](), [migration](), [Open Source](), [MkDocs](), [Markdown](), [OpenAPI Specification]() Tags: [blog](), [configuration](), [docs-as-code](), [documentation](), [markdown](), [migration](), [open-source](), [openapi](), [static-site](), [static-site-generator]() ### AI overview Doctave announces that it will shut down on September 14, 2026. Hosted documentation sites, the dashboard, and builds and deploys will stop operating. Users can continue working from their Git repositories and can migrate to the open-source Docapella static site generator, although server-dependent features such as analytics are unsupported. ### Source excerpt After several years of building documentation tooling, we've made the difficult decision to shut Doctave down. The service will stop operating on September 14th, 2026. We have informed all our customers individually, but are also now posting a public message here. On September 14th, Hosted documentation sites will stop being served The Doctave dashboard will no longer be available Builds and deploys will stop running How this impacts you Your content is yours, and it's already in your repository. Doctave was built on docs-as-code precisely so that your Markdown, OpenAPI specs, and configuration live in Git rather than in our database. Nothing needs to be exported from us to keep writing. You own your docs. Where can I move my docs? We have created an open source static site generator, Docapella, that is mostly compatible with existing Doctave projects. The main change you need to make is renaming doctave.yaml to docapella.yaml. Features that require a server, such as analytics, are not supported, but the content model and general look and feel are the same. Thank you To everyone who wrote documentation with Doctave, sent us feedback, filed bugs, or took a chance on a small team building documentation tooling: thank you. We learned an enormous amount from you, and it genuinely mattered to us. If you have questions about the shutdown or need help planning a migration, get in touch at nik@doctave.com. I'll answer every email I can before we wind things down. - Nik & Anton ## Doctave Studio 2.0 Beta: The editor for technical writing and docs-as-code DevFeed: [Doctave Studio 2.0 Beta: The editor for technical writing and docs-as-code]() Original publisher: [Read original article]() Author: Doctave Team Published: 2024-10-08T05:00:00Z Content type: release Language: en Sources: [Doctave - Build beautiful developer portals with docs-as-code]() Topics: [Documentation](), [Tooling](), [Markdown](), [OpenAPI Specification](), [CI/CD]() Tags: [announce](), [assets](), [auto-complete](), [beta](), [blog](), [ci-cd](), [components](), [docs](), [docs-as-code](), [editor](), [real-time](), [technical-writing]() ### AI overview Doctave announces the public beta of Doctave Studio 2.0, an editor for technical writing and docs-as-code. The beta includes a modern editor, real-time Markdown and OpenAPI previews, auto-complete for links and assets, and inline Markdown error reporting. ### Source excerpt We're excited to announce that Doctave Studio 2.0 is now available in public beta! Doctave Studio is a new editor for technical writing and docs-as-code, and we're excited to share it with you. Want to see it in action? Here's a quick introductory video of Doctave Studio 2.0: If you just want to see how to participate in the beta, you can jump straight to the end of this post Why build a new editor? One of the biggest issues with docs-as-code is inconsistent tooling. While there are great tools out there (like Vale), it's really hard to create a great authoring environment for docs-as-code. Getting spell check, broken links checking, auto-complete, and more configured is often too complex or time consuming, that lots of authors live without these tools. This problem is compounded when you have multiple authors collaborating on the same documentation. One will have a spell checker configured, one will have auto-complete configured, another doesn't have a broken links checker. The lack of a common authoring system causes friction, confusion, and ultimately raises the barrier for contributions. And after all that, you still need to set up these same checks in your CI/CD pipeline! This is what we set out to solve with Doctave Studio 2.0. We've already made it easy to host, version, and review docs-as-code projects with our existing product. Now we're taking the next logical step and improving the docs-as-code authoring experience. What's in the Doctave Studio 2.0 beta? Today we're launching Doctave Studio 2.0 into beta with a few key features: A new, modern editor with a focus on the authoring experience Real-time previews of your content as you type (Markdown and OpenAPI!) Powerful auto-complete for your links, assets, and components Great error-reporting inline in your Markdown Let's see some of these in action! Real-time previews The right-side panel in Doctave Studio is dedicated to a real-time preview window. It shows you what your content will look like once publi ## Markdown vs. DITA: Balancing Simplicity and Structure in Technical Documentation DevFeed: [Markdown vs. DITA: Balancing Simplicity and Structure in Technical Documentation]() Original publisher: [Read original article]() Author: Niklas Begley Published: 2024-06-06T07:00:00Z Content type: comparison Language: en Sources: [Doctave - Build beautiful developer portals with docs-as-code]() Topics: [Markdown](), [Documentation](), [XML](), [HTML](), [OpenAPI Specification]() Tags: [blog](), [docs-as-code](), [documentation](), [html](), [markdown](), [openapi](), [technical](), [technical-documentation]() ### AI overview This comparison examines Markdown and DITA as authoring choices for technical documentation. It presents Markdown as easy to learn and widely supported, while describing DITA as a more structured XML standard that supports content reuse, document consistency, and publishing in multiple formats, with a higher learning curve. ### Source excerpt When embarking on a new documentation project, one of the first, and quite consequential choices you have to make is what tools and formats to pick. Do you go with Markdown, the ubiquitous and light-weight markup language with a low barrier to entry, or do you instead reach for an authoring system like DITA that lets you enforce structure and reuse content from day one? In this post we're going to look at both options and evaluate the pros and cons of both approaches, and when one might choose one over the other. What is Markdown? Markdown was originally developed by John Gruber back in 2004. It was designed as an easy way to convert text into HTML easily. Here is John describing Markdown in the introduction: Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML). 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 # Rocket Launch Sequence 1. **Pre-launch Jitters** - Double-check that the pointy end is facing up - Ensure the rocket isn't just a giant firework - Cross fingers and hope for the best 2. **Blastoff!** - Light the candle and watch the show - Try not to think about the astronomical fuel costs - Wave goodbye to the rocket (and your paycheck) 3. **Celebrate or Commiserate** - If the payload reaches orbit, break out the champagne - If not, break out the tissues and start drafting the apology email - Either way, start planning for the next launch (and budget) Example Markdown snippet Since then, Markdown has exploded in popularity. It has become the lingua franca for all kinds of technical content and blogs. Developers have embraced the simplicity of Markdown. Most new programming languages support Markdown as part of their docstrings, OpenAPI supports Markdown in description fields, and most static site generators have built-in Markdown support. The ecosystem of Makdown tooling is vast. This is why the docs-as-code movement has mo ## The path to structured content with Markdown DevFeed: [The path to structured content with Markdown]() Original publisher: [Read original article]() Author: Niklas Begley Published: 2024-06-06T07:00:00Z Content type: tutorial Language: en Sources: [Doctave - Build beautiful developer portals with docs-as-code]() Topics: [Markdown](), [Parser](), [Parsing](), [XML](), [Documentation]() Tags: [authoring](), [blog](), [documentation](), [markdown](), [structure](), [structured](), [syntax](), [technical](), [technical-documentation]() ### AI overview The article argues that Markdown has an underlying structure that is often hidden from authors, making it more similar to XML-based structured authoring than commonly assumed. It demonstrates how Markdown is transformed into an abstract syntax tree and represented as a tree-shaped JSON structure. ### Source excerpt This post was inspired by the Pros and Cons of Using Markdown for Technical Documentation Panel Discussion with Ed Marsh, Eric Holscher, and Fabrizio Ferri-Benedetti. Around the ~40 minute mark the discussion moves onto how to maintain a consistent style with Markdown documentation, especially in larger teams. The panel agrees that currently there are no clear ways to enforce a specific document structure when using Markdown. Fabrizzio then on goes on to say (54:15): Some day, someone is going to figure out a way to seamlessly grow Markdown into something that can mature into structured content I've been thinking about this a lot, and my claim is that Markdown and XML (which is traditionally used for structured authoring) are more similar than you would initially expect, and that the dream of adding validations and structure to Markdown is perhaps not too far away. The structure behind Markdown There's a commonly held belief that Markdown is not structured. There is some truth to this, but I'd argue it's more the case that the structure is hidden. While with most XML-based authoring tools you are manipulating the structure directly (or through a WYSIWYG editor), with Markdown we are one level removed from the actual underlying structure. To demonstrate, let's take a look at a quick example at how Markdown is actually almost equivalent to XML, if you squint a little. Let's take this Markdown content. 1 2 3 4 5 # Hello, world This is a paragraph **with some bold text** and this is an image When this Markdown is processed into HTML, it goes through a number of transformations. The first thing that happens is that the Markdown is converted into an Abstract Syntax Tree. This means taking the raw text of the Markdown, and converting into something more structured that a program can manipulate. Each Markdown parser does this a little bit differently, but we can see this in action with, for example, the AST Explorer tool. Let's take Markdown above, and paste it ## Ballad: Doctave's Markdown-aware component system DevFeed: [Ballad: Doctave's Markdown-aware component system]() Original publisher: [Read original article]() Author: Doctave Team Published: 2024-05-27T07:00:00Z Content type: release Language: en Sources: [Doctave - Build beautiful developer portals with docs-as-code]() Topics: [Markdown](), [MDX](), [Parser](), [Documentation](), [ui]() Tags: [blog](), [components](), [documentation](), [elements](), [markdown](), [mdx](), [render]() ### AI overview This release article explains Ballad, Doctave's Markdown-aware component system introduced in Doctave 2.0. It describes embedding UI and layout components in Markdown with an MDX-inspired syntax, combining components with Markdown, using expressions for user preferences, and creating custom components. ### Source excerpt Doctave 2.0 is out, and the biggest new feature in this release was our new component system, which we're calling Ballad. In this post we want to talk about the path we took to get here, why we felt none of the existing solutions worked well for us, and what our component system enabled. Ballad brings interactive components like tabs to your Doctave docs Why do we need components? Ballad lets you intersperse UI components in between your Markdown content. While Markdown is fantastic for simple prose, most documentation projects inevitably need widgets like buttons, cards, and callouts (or admonitions), or more complex layouts to keep the content clear and engaging. This is what we're solving with Ballad. How it works In short, you can add HTML-like tags into your Markdown, which Doctave will render into various components. Let's look at a basic example: adding a Button component into your documentation: 1 2 3 Click below to read more. This gets rendered like so: Sometimes a regular Markdown link just doesn't cut it Components Our components come in two flavors: UI components and layout components. The former are components like