website: use SSG and markdown docs

[yochem]

TL;DR: POC of markdown generated website in https://github.com/yochem/jqdocs, currently the 'hugo' branch.

This proposes to continue the incredible work done in #3189, to convert the documentation fully to markdown and drop the custom python generation from yaml content. It is meant as a future update, and if wanted, I will start working on it seriously after #3189 is merged.

The markdown is converted to the manpage using pandoc (as implemented in #3189), and deployed as website using a static site generator.

Markdown is easy to read and write. Markdown written in a yml file is not. You can't use your editors features, and writing/debugging/testing the examples is also hard. Having the docs in markdown also allows easy readability on GitHub, see for yourself.

Ideas to discuss

• Which SSG?
  • Jekyll: built into GitHub, slow, but works fine. Not that much functionality / flexibility.
  • Hugo: Very fast, flexible, and extendable. Can for example include code files (so example can be in .jq files, e.g. be in examples/dot-op.jq)
  • Pandoc: Not a SSG, but already used for the manpage. Can also do some templating / markdown including, but probably requires more manual work
• Website in it's own repo
  • Pro: jq repo get's lighter, removing code that is not necessary for jq itself
  • Pro: build / deployment is a bit easier
  • Pro: separation of concern
  • Con: need to decide on where to place the actual docs (markdown content). Do we want to have all docs in a separate repo, or keep it close to the code, thus in the jq repo, and pull that content to the website repo with a github action?
  • No need to save the documentation for every version in a folder anymore, we can pull the documentation for every tag 'v*' to the website repo (would need to backport the 'new style' docs to the version tags)
• as I suggested in Domain name for jqlang.github.io/jq/ #3219, it might be a good idea to buy a domain name for the website
• and probably more...

Progress

I created a POC at https://github.com/yochem/jqdocs.

One of the concerns raised in #3189 (comment) is that the manuals of old versions also need to be converted. I created a small POC for this conversion with a python script. It's currently in the jqdocs repo, along with the resulting markdown manuals, to give a taste of what that looks like. There is still a lot of room for improvement: sections can be split over multiple files, code examples can be in in own files (ex-1.jq, ex-1-output.json, etc.).

I also created a small POC of a Hugo repo, but it's not in the repo yet. I'll update you when it is.

Let me know what you think! Are these good suggestions? Welcome to explore this idea?

P.S. I understand that #3189 is already a huge update, and required quite a lot of time and effort from its author and the maintainers of jq. Therefore, if you want me to continue on this, my goal will be that the PR is relatively burden free for the maintainers:

• As less visual changes to the website as possible. No content updates, no layout changes.
• I want this to be a drop in replacement. Let it build via GH actions, little personal workflow changes required for the maintainers.
• The result should be simple, and understandable. Just markdown content. No weird extensions of markdown/hugo, minimal custom code.

I hope these changes will make it easier to update docs, and that you can write code/markup in the right filetype: no more markdown in a yml file that also contains jq and json code. This will probably make it a lot easier to debug/test/use the features of your editor!