Idea: move documentation to wiki or static site

[fetwar]

A discussion to track the idea discussed off-topic in issue #2708 about moving the gopass documentation to Github Wiki or similar.

This would allow easier access to documentation for end users in a more readable format.

@AnomalRoil and @dominikschulz

[fetwar]

But as an experiment I just tried pushing our docs repo to our wiki repo, but sadly, it seems the Wikis aren't really respecting the notion of "folder hierarchy" and since we have multiple files with the same names in different folders of our doc, like "config.md" in docs/commands/config.md but also in docs/config.md, it seems to mess it up quite a bit and it "hides" some of them, because then you can't access them it seems (although their titles do appear in the sidebar...)

In general it seems Folder are not supported by GH Wikis: https://github.com/orgs/community/discussions/23914

I guess we might do a selection of a "few" doc pages to sync with the wiki, tho. Seems it would be easy to automate with a GHA and some bash.

We could also use github actions to generate a static site from the markdown documentation, allowing for directory hierarchy support, custom CSS and if deemed beneficial, support for relaxed markdown format as opposed to strict markdown (single newlines etc)

[AnomalRoil]

It should be fairly easy to add our documentation to the gopass.pw website, to be honest, since we already use a static generator and GHA:
https://github.com/gopasspw/gopasspw.github.io
and Jekyll supports markdown afaik.

[koalp]

Does the website use a static generator ? I do not find the source.
If none is used I might be tempted to draft a PR for a statically generated documentation using hugo and something like hextra
(or any other static documentation tool, docusaurus, mkdocs, mdbook, …)

[AnomalRoil]

Yup, it's using Jekyll under the hood: https://github.com/gopasspw/gopasspw.github.io/deployments/github-pages

[fetwar]

Oh awesome, would streamlining the repos and documentation experience be something you are interested in seeing done? If so is there anything I could do to help?

Unifying the documentation to a single point of truth would make things much easier to follow in my opinion, browsing the current docs in Github is a bit painful.

[fetwar]

I've heard good things about Jekyll in the past and believe it to be a good fit for the static site generation from Markdown, I have not personally used it though.

From my research Jekyll does support markdown through 2 available markdown renderers, depending on which is used it can be quite customisable with things like how "strict" the markdown requirements must be, or relaxed (such as allowing single line breaks).

Supported Markdown renderers for Jekyll.

I believe Kramdown would be the most simple to achieve minimum viable product and the most configurable, strict markdown is already used in the GoPass docs, so swapping over shouldn't be hard at all.