docs-deploy VS mkdocs-material

You can get yours: https://github.com/chevere/docs-deploy (I know, it has some bits on Spanish. I made it for my team but I can translate it if people need to consume this).

Here's the deploy repo https://github.com/chevere/docs-deploy

For anyone looking for a doc generation tool:

I was lately evaluating several tools like VuePress, Docusaurus and AsciiDoc.

I ended up using Mkdocs Material (https://squidfunk.github.io/mkdocs-material/). If you haven't already, have a look. I think it is pretty impressive. From tags, tabs to the fantastic built-in search ...

I recommend checking the list of OpenSource projects that use Material for MkDocs [1], for example FastAPI [2]. Alternatively, you can clone the Material for MkDocs repository, as the docs are built with itself.

[1] https://github.com/squidfunk/mkdocs-material#trusted-by-

You end up with markdown split into logical folders, with a natural flow from each page to the next built in.

It’s built with python but you don’t need python knowledge at all to build; configure and serve the product.

The plug-in eco system adds the ability to embed variables into the markdown pages also you can embed html, so d3 visualisation or a vue calculator app will all embed just fine.

Really clean extensible base, insanely simple and fast to get started oh and free to use. I push mine to GitHub and have that auto build into GitHub pages or a free Netlify account.

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

For those that want to turn their markdown files into prettier HTML websites, there are tools like Material for MkDocs. Of course, this involves a lot more work and you’d need to host it on a separate site or enable GitHub Pages on the repo but it’s one way that I’ve found to keep the markdown files free of HTML.

My favorite so far is https://squidfunk.github.io/mkdocs-material/

Documentation, that should be the first thing you use. Documentation is the basis for all the things you do, it can be adapted and is implementation independent. If you want a framework to make it easy mkdocs material is nice.

I love markdown, and MkDocs is my go-to tool for writing documentation, but it’s pretty bare. mkdocs-material is a template that you can put mkdocs on… except it packs a whole world of additional features: versioning your documentation, a native cookie consent solution, rich search previews, and a truckload of other things… seriously give the guy 10$ a month to get supporters-only features, and you’ll get the only documentation tool you will ever need. (for instance, the AWS Copilot CLI docs were written with this, see for yourself, that’s amazing).