Doctave: an opinionated documentation site generator

Hi all!

I've been building a documentation site generator in Rust: Doctave. And version 0.1.0 is finally out! What makes Doctave different from open source static site generators is that it's only focused on Markdown documentation and comes with documentation-related tools already built in. It's quite opinionated, and requires little to no configuration to build a docs site.

Some features of note:

  • Mermaid.js diagrams
  • Full-text search
  • Local live-reloading server
  • Responsive design
  • Dark mode
  • GitHub flavored markdown
  • Minimal configuration

You can find the docs for it (built with Doctave itself) here.

Would love to hear your feedback if you try it out!
Cheers,

https://github.com/Doctave/doctave

8 Likes

This looks quite promising!

I've got a couple follow-up questions

  1. How would you say Doctave compares to other documentation tools like mdbook?
  2. You mention it being "opinionated", does that just mean commonly used tools/features are built in ("batteries included"), or does the tool force users to follow a particular way of doing things?

It's also really nice to see you provide good documentation to new users and invested some time in the rendered document's styling, layout, and colour schemes. A lot of effort has been put into Doctave and it shows.

Thank you for the kind words!

To answer your questions, the main difference is that Doctave is, like you describe, batteries included. It makes some decisions for you, like including Mermaid JS for diagrams and the general look and feel, and doesn't have too much room for customization.

This means that for many projects, where docs are stored as Markdown next to your code, you can just start writing your docs and get a great experience immediately without tweaking plugins or HTML templates.

The downside is that Doctave won't work for every project. If branding/design is critically important (like a company's public API docs), or you want some special integrations, you are probably better of with something like Jekyll or Hugo.

For the case of mdbook, I'd say the difference is that mdbook is designed for longer-form writing (like the Rust Book), while Doctave would be more suited for writing docs alongside your code. mdbook descibes itself as "a utility to create modern online books from Markdown files", which is different from Doctave's goals.

2 Likes