docsify VS mkdocs-material

Hello, FYI: I used https://docsify.js.org/ that turns markdown files into a static website without the need of building the site locally or in a CI. Example config. my 2c.

After reading your post again and this comment, I don't think Jekyll is the best choice. Something like GitBook, MkDocs, or Docsify would be a better solution as they let you control the organization and flow much better.

Docsify

On a new side project I'm working on I need to have a fair amount of documentation for usage, implementation, options, etc. In the past I've used https://docsify.js.org hosted on Vercel, but I was curious if there is anything else out there people like. Looking for free or paid options. So long has I can host on a subdomain I'm indifferent.

Thanks!

Docsify is a client-side only documentation generator. As a user requests a documentation page, it would fetch the associated .md file and render it all client-side. That meant that our documentation deployment process was simple again, as we could just push changes to the main branch and BOOM they would show up within seconds.

+1 more for Docsify and its Github repo. I know this subreddit is for self-hosted things, however I wanted to add Docsify works well with Github Pages (they host, you plug in your domain or subdomain).

https://docsify.js.org/#/ SSGs are too complicated.

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