Decide on static HTML building tool

[jcohenadad]

Jekyll, Hugo, Sphinx, Mkdocs?

I would vote for Jekyll or Mkdocs.

Jekyll:

• Popular
• No need for speed (ie we won't have thousands of pages)
• Good integration with GH pages

Mkdocs:

• @po09i already has a working build
• https://people.xiph.org/~epirat/post/why_switch_to_mkdocs/

Resources:

• https://idratherbewriting.com/learnapidoc/pubapis_which_tool_to_choose.html
• https://www.techiediaries.com/jekyll-hugo-hexo/
• https://www.docslikecode.com/learn/

[rtopfer]

If it's just a matter of converting our Markdown documentation files to HTML is it safe to assume there wouldn't be any major differences apart from convenience?

Can we anticipate needing to add material that can't just be included in a Markdown file?

[alexfoias]

I vote Jekyll. @rtopfer Jekyll uses markdown format that is dynamically rendered to HTML using GH pages.

[rtopfer]

@alexfoias not important but i thought it was the other way around, with Jekyll rendering the text files to HTML and GH Pages simply hosting the content + providing convenient editing features?🤔

[jcohenadad]

Can we anticipate needing to add material that can't just be included in a Markdown file?

absolutely-- figures, movies, etc. can be physically located in the repos source (e.g. _media/) and pointed at from within the markdown page.

However i am not aware of GH page having "convenient features" for editing. I think everything is done according to mkdocs or jekyll mechanisms (e.g. fill markdown pages and compile)

[jcohenadad]

If we go with GH page, the default build processor is Jekyll. If we want to change the default build processor, here are the instructions.

[po09i]

Since I had a working build for mkdocs I implemented it using this github action. I'm not familiar with jekyll but I can look into it if I missed something mkdocs does not do. Currently works really well.

[jcohenadad]

@po09i can we close this?

[po09i]

Yes, we went with mkdocs.