Just posted a new article to the blog. Warning this is about twice as long as the other posts. If you are interested in hearing the mental process that went into starting the blog and what I hope to gain from using Hugo to manage it, give it a read. If you are not terribly interested in more of a meta style post, you might spend your time better watching your favorite Youtuber. Take care everyone.
Thanks for taking the time to do your blog and sharing with us!
thanks for the inspiring longread
brief quip re.
- I want to become proficient in using all of the syntax in Markdown.
https://media.ccc.de/v/froscon2019-2389-documentation_with_any_editor#t=2779 made me a asciidoc devotee btw
and there’s a regularly updated asciidoc SSG list at https://gist.github.com/briandominick/e5754cc8438dd9503d936ef65fffbb2d
Thanks @Kor_Ben for the links. Actually, I fell in love with Asciidoc years ago, like in 2006, but then failed to make regular use of it until about 18 months ago. My son, who loves to program, loves Asciidoc too. He has built a vim plugin for it because he loves it so much. He even built us a Asciidoc file viewer as a Python web app that runs on our home server allowing us to use it as our personal wiki.
I would kind of like to stick with Asciidoc for everything, but I have a couple reasons for using markdown instead:
I’m working on a documentation project, and would like to encourage collaboration with other community members. Although Asciidoc is similar to Markdown there are differences, and Markdown seems to have a broader audience than Asciidoc at this time. The default editor in the Linux Distro that I’m writing documentation for supports Markdown, but doesn’t support Asciidoc syntax.
Hugo works out of the box with Markdown, adding Asciidoc support might be something I look into in the future, but I need to start cranking out more articles on my blog and finish some of my other blog admin tasks before I tackle adding Asciidoc support, and I have read there might be some hiccups with adding Asciidoc to Hugo as well.
While looking for solutions for the documentation project mentioned in #1, I have found plenty that will work with Markdown, and the have all of the features I’m looking for.
- Easy integrations with Github (where all of the source code and documentation are currently managed)
- Easily create PDF from Markdown Documentation.
- Easy to set up a testing environment for the Documentation.
With the criteria above, Docsify seems to stand out above other solutions. For a while I thought about using Hugo since I already have it set up for my blog, but I can’t find a clean easy workflow to convert a Hugo site created with a Documentation Style Theme into a PDF. Next I thought about Antora because I was familiar with the fact that Fedora uses it for all of their documentation, but that seemed a little complex to get set up, and I don’t know if they have an easy PDF export. Docsify was easy to set up the testing environment, and they have a PDF conversion tool extension, but it is decidedly focused on Markdown.
We will see though, I made a proposal to make a move to using Docsify and Markdown for the project documentation. If there is little interest from the development team or community, I might just head back to Asciidoc because I would be working only on personal projects with it, and wouldn’t need to collaborate with others.