Hello all,

I was tasked at work to see if I could come up with a more intuitive documentation system for us. Currently, we use markdown in vscode and then use Github to sync them. The system works but we are limited to basic markdown.

We are looking in to incorporating some more advanced things like callouts/admonitions for something visual that grabs our attention for things we need to watch out for. This one is a requirement.

Another thing that would be really awesome is if there is a way to inject text from other places. One thing that comes to mind is if we have software for a certain line of devices. Currently, we do a search all and replace but it’s not a foolproof as we would like. Most of the time, someone will change the software on the do they are working from but not replace all of the others in the same line of devices. If we could set it once somewhere and then pull it in to all of the docs, that would be really nice. Not a requirement, but this would put a program high on my list.

Templates is also on my wish list. We have a master template that should be copy/pasted in to a new doc but some of our team will save in to the master and then I have to go back and undo all of their changes. I am imagining that we create a new file where it needs to be and the template will automatically be imported in.

We have Notion but I don’t really like it. It is very clunky in my opinion. I mean, I can’t even do a simple calendar with recurring events easily.

Mkdocs has been shot down in the past. I am unsure why.

I am partially looking in to Obsidian but a lot of the features would be plug-ins and I am kind of looking for a minimal setup approach for new users.

Thanks for any suggestions!