4 ms·

I've been exploring a lot of these tools recently and it seems like there are two ideologies. Hugo, and many others in the jamstack/SSG space, are basically fu

I've been exploring a lot of these tools recently and it seems like there are two ideologies. Hugo, and many others in the jamstack/SSG space, are basically full-fledged content management systems. These come from a long line of tools all meant to basically replace Wordpress in a content-focused workflow. This means they support a lot of bells and whistles with document schema (categories, tags, site maps, etc. etc.) and taxonomies. There are even workflows like draft posts, setting future publish dates, etc. (again very Wordpress inspired). You could build a recipe collection site just as easily as a technical documentation site with hugo for example. 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 https://backstage.io/blog/2020/09/08/announcing-tech-docs That's a pretty strong endorsement IMHO.

cryptos 5y ago
Since most developers don't like to write documentation, it is important to make the hurdle to write as low as possible. For me AsciiDoctor is the sweetspot because it is easy to setup, has good tool support (for example VS Code and IntelliJ), supports many text features and is relatively easy to learn (if you would only use the features known from markdown, it is as easy to learn as markdown).
- qbasic_forever 5y ago
  Yeah asciidoc is pretty slick. I wish pandoc had more love/support in the SSG world as it can handle basically every doc format known to man with ease, and even enable fancy logic with AST filters in lua scripts. Why not use md, asciidoc, rst, etc. wherever you want. 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).
sandreas 5y ago
Thank you, that comment is very enlightening... I know hugo pretty well, so this might have been not as obvious to me. One of the things, I did not like so much about hugo (although I think it's awesome), is documentation. It is pretty well documented but as you said the sheer amount of options is overwhelming. 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 Since all this IS possible with hugo, you just have to find your way to do it, I think ;)
- qbasic_forever 5y ago
  Yeah hugo kind of suffers from being one of the first popular tools in the SSG space. It's been around for a while and feature creep has definitely added to the complexity. Being written in Go is both a huge advantage, and an unfortunate disadvantage too these days. 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.
  - chrisweekly 5y ago
    +1 insightful 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.
squidfunk 5y ago
> 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. 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!

cryptos 5y ago

Since most developers don't like to write documentation, it is important to make the hurdle to write as low as possible. For me AsciiDoctor is the sweetspot because it is easy to setup, has good tool support (for example VS Code and IntelliJ), supports many text features and is relatively easy to learn (if you would only use the features known from markdown, it is as easy to learn as markdown).

qbasic_forever 5y ago
Yeah asciidoc is pretty slick. I wish pandoc had more love/support in the SSG world as it can handle basically every doc format known to man with ease, and even enable fancy logic with AST filters in lua scripts. Why not use md, asciidoc, rst, etc. wherever you want. 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).

sandreas 5y ago

Thank you, that comment is very enlightening... I know hugo pretty well, so this might have been not as obvious to me. One of the things, I did not like so much about hugo (although I think it's awesome), is documentation. It is pretty well documented but as you said the sheer amount of options is overwhelming. 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 Since all this IS possible with hugo, you just have to find your way to do it, I think ;)

qbasic_forever 5y ago
Yeah hugo kind of suffers from being one of the first popular tools in the SSG space. It's been around for a while and feature creep has definitely added to the complexity. Being written in Go is both a huge advantage, and an unfortunate disadvantage too these days. 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.
- chrisweekly 5y ago
  +1 insightful 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.

squidfunk 5y ago

> 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. 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!