Ask HN: Any good plug'n'play static site generators for docs?

6 points by longrod 3 years ago | 4 comments

I have been searching for a good and simple to use static site generator to generate documentation for one of my projects. The problem is all the good ones (docsaurus, nextra etc.) require complex setups. I know it's simple for a developer but I want it to be easy for contributors to preview their changes. Not everyone has a NodeJS setup.

I know GitBook exists but it's not OSS and is fairly complex on its own: a whole platform with its own learning curve.

I am looking for something that can:

- generate documentation from markdown - minimal but modern design (doesn't have to be configurable) - zero setup/dependencies i.e. plug'n'play

Here's the workflow I am looking for:

- clone

- install xyz for platform

- make edits

- xyz dev/start

I have explored Hugo and Zola but I don't like the multiple directories they create for themes, CSS, js etc. I want the generator to be self-contained.

The reason I am here asking is if someone has a personal project that does something like this that they'd like to share. Or if someone is working on something similar and would like users.

KolmogorovComp 3 years ago |

mdbook: https://rust-lang.github.io/mdBook/

> Publishing a book

> Once you've written your book, you may want to host it somewhere for others to view. The first step is to build the output of the book. This can be done with the mdbook build command in the same directory where the book.toml file is located:

> `mdbook build` This will generate a directory named book which contains the HTML content of your book. You can then place this directory on any web server to host it.

james-skemp 3 years ago | |

I'm not sure this meets the OP's requirements, but this is what I was going to recommend as well.

I've used mdBook exclusively since moving off GitBook in 2019 when they dropped their OS/local project and highly recommend it for how easy it is to setup and use.

knewter 3 years ago |

https://squidfunk.github.io/mkdocs-material/

This is my go-to mkdocs theme for documentation

Tomte 3 years ago |

mkdocs: https://www.mkdocs.org/