miniscruff/changie

Switch to mkdocs for documentation

Closed this issue · 5 comments

miniscruff commented

The hugo template I used is fine but I think having search will be great and it has been kind of a pain to add new pages and stuff. So going to mark this down as something I want to consider changing.

Requirements:

  • Must support markdown content files ( cobra and my own gen command generate markdown files )
  • Must support github actions/github pages ( pretty easy )
  • Should have built-in or optional support for searching
  • Should integrate with vhs built animations #467
  • more?

Ideas:

Consider: https://docsearch.algolia.com/docs/who-can-apply/ or https://pagefind.app/

sheldonhull commented

Take a peek at docusaurus if you feel adventurous, of if you want to get up and running quick....

I have mage fully quote with notes.sheldonhull.com. You can look at https://github.com/sheldonhull/digital-garden and if you clone and run mage you'll see the dockerized mkdocs run, build, serve. The github actions use this too.

This mkdocs powered site is one of the best for "plug and play" docs.
Docusaurus (I've been testing migration to this as well on my own knowledge base) is also very promising out of the box.

I'd be willing to take a swing at a draft mkdocs based site using what I've built on my own if you like, if you aren't in a rush.

miniscruff commented

I have mage fully quote with notes.sheldonhull.com. You can look at https://github.com/sheldonhull/digital-garden and if you clone and run mage you'll see the dockerized mkdocs run, build, serve. The github actions use this too.

This mkdocs powered site is one of the best for "plug and play" docs. Docusaurus (I've been testing migration to this as well on my own knowledge base) is also very promising out of the box.

I'd be willing to take a swing at a draft mkdocs based site using what I've built on my own if you like, if you aren't in a rush.

Yea I think I will go back to my usual material mkdocs setup, Docusaurus seems fine but using React feels a bit excessive for my needs.

miniscruff commented

For anyone curious or for my future self, the tedious part about this conversion comes from the custom markdown generation I built as part of make gen and how it builds docs for the configuration and potentially the cobra CLI gen. There are also some custom work done as part of the template on top of that for adding code links and share links.

sheldonhull commented

The branch I mentioned has functional mkdocs invoked by Mage.
However, I've been sticking so far with hugo as well.

While it's not perfect, I was able to reproduce the tree view on the side and give myself some flexibility.

Might consider this if you want to keep your custom rendering but just restyle some things.

Personal docs example

I've got things to update and improve, but overall I've decided to stick with hugo rather than try to fit in the mkdocs world due to my custom content.

miniscruff commented

I was recently starting a new project and started from scratch with mkdocs and I like it a lot. Hugo has been great but a lot of the hard work is done by themes and I just couldn't really get behind any of the themes. Material for Mkdocs is just too good in my opinion. There are a few like astro and docusaurus that make sense if you are a javascript project, but for plain markdown material for mkdocs is the go to for me.

https://github.com/miniscruff/scopie has all the stuff I want to use, I just need to swap some codegen stuff around and I should be all good.

  • 👍1