This is a nice tool. Is there an advantage over a static site generator like hugo with a documentation theme? I mean despite the fact, that this explictely targets documentation...
e.g. https://themes.gohugo.io/doks/ or
e.g. https://themes.gohugo.io/doks/ or
On the other end of the spectrum you have tools like MkDocs (or mdbook, docsify, docusaurus, etc.) which are more focused on technical docs in markdown format. These tools put much less emphasis on schema, layout, taxonomy and really try to go from a pile of simple markdown files to a rendered site with as little friction as possible. You typically just lay out files in the filesystem, make simple markdown links between files, and the tool takes care of all the details of building a doc site like layout, rendering, linking, table of contents, and even search.
The big tradeoff between them is complexity. There's a _lot_ to learn to fully use something like hugo. You can spend days going through all of its features and building complex asset processing pipelines, themes, taxonomies, workflows, etc. But this is also a bit of a downside if you just want to turn some markdown files into simple technical docs--you have to do a bit of organization, add frontmatter, and learn a few hugo quirks. You'll have a fancy base to really go wild and add tons of content... but for technical docs you might not need all that power and complexity.
MkDocs strikes a really nice balance in this regard--you basically just write markdown files with simple links and it will figure out the rest. The Material theme here is _very_ slick and one of the best out of the box themes you'll find for any technical docs generator (or even SSG in general) period. This combo is so good Spotify use it heavily in their developer portal system Backstage: https://backstage.io/blog/2020/09/08/announcing-tech-docs That's a pretty strong endorsement IMHO.
What I was missing, is a list of quickstart best practise scenarios along with a well designed template for exactly this use case, like:
- A small blog
- A companies homepage
- A photographers website
- A technical documentation with search index
- An image gallery
It's great because the speed and ease of use is unrivaled, but nowadays a jamstack site is much, much more than just a pile of markdown turned into HTML. People are building complex SPA, SSR, hybrid, etc. architectures and using fancy webpack-based workflows with all kind of transpilation, code generation, etc. at every level. You have to jam all of that into hugo's workflow and it just adds to the complexity--now you need a full node/JS frontend setup (with webpack/babel/postcss/etc.) and hugo's setup on top of that. Hugo tries to do some of this itself with esbuild but it still is hard to get away from bolting on webpack with hugo and getting the best... and worst... of both worlds.
Along these lines, the case for exporting a static site from NextJS (leaving the door open to all the options) is a lot stronger than trying to bolt on dynamic functionality to Hugo. IMHO it's not even close.
My dream setup would be something with simple file-based routing like MkDocs, all of the rendering formats and power of pandoc, and the ease of deployment and speed of a Hugo-like static binary in Go (just one exe and you're done).
That's exactly the value proposition of Material for MkDocs. Just throw Markdown at it and tweak it with some configuration, if desired.
> MkDocs strikes a really nice balance in this regard--you basically just write markdown files with simple links and it will figure out the rest. The Material theme here is _very_ slick and one of the best out of the box themes you'll find for any technical docs generator (or even SSG in general) period.
Thanks!