Do we need a new static site generator for project documentation?

Tools
1

Over and over, I find myself needing a static site generator to extract documentation from a Git repo, and put up a static site. There are dozens of static site generators available, but almost all of them suffer a fatal flaw that they you can’t have images next to the Markdown files in the source files. Most require them to be in a separate “public” directory with other static assets. This ends up resulting in most projects have separate documentation repositories from the source repositories.

Zola is a little different in that it allows you to have an image next to a Markdown file (asset colocation), but it creates pretty URLs (without .html extension), so you end up doing a lot of mypage/_index.md instead of simply mypage.md.

Proposal: what if we had a simple tool that do a simple translation on a directory of markdown files where the exact directory structure was retained and mypage.md simply becomes mypage.html. This would keep the documentation source files simple and easily viewed in the Github web interface, as well as a static site.

I’ve concluded the following about documentation:

  • best if created by project authors
  • needs to be close to the design/src files and part of the design workflow
  • needs to be very simple – complex formats, tooling, metadata, or structure introduces friction

Really, what I’m talking about is roughly generating a static site that looks about like what Github might generate, along with some extras like a table of contents, search, code syntax highlighting, etc.

Documentation is a critical part of any development process (OSS and otherwise) – I think it deserves focused tools.

I hesitate to get distracted on yet another OSS project, but I’m currently spending too much time setting up tooling for documentation sites for my various projects.

Thoughts?

2

A post was split to a new topic: mdBook

3

In general, I don’t find a need to generate static documentation. I can survive quite well by leaving documents in Markdown *.md format and include images in a nearby folder, linked into the respective Markdown file. Converting this to HTML is never really needed. Users who want to view the documentation can do so within tools like Gitea pretty easily.

4

I think that is the pragmatic approach for developers – that is one reason I’m so insistent that my doc gen tools can extract documentation that is perfectly usable in Github – that is where most developers will use it. Users might be a different story though – most people are used to nice documentation sites with easy to navigate outlines. Hopefully, a nice doc site will also help with project marketing. Anyway, this point is almost irrelevant now as mdBook makes it so easy to extract plain-ole markdown docs from a project repo, and should be almost no effort to maintain going forward:

https://docs.simpleiot.org/

One side benefit I’ve found is mdBook will check for broken links – that is a huge help in keeping quality of docs up.

1 Like