documentation: mkdocs for mergerfs, first draft

[oregonpillow]

Is your feature request related to a problem? Please describe.
The Documentation for mergerfs is outstanding, but can sometimes make it difficult to find information due to the large, single file README.

Describe the solution you'd like
I've seen it mentioned before, I think even by yourself, that the plan is to migrate to a static site generator for documentation.

Describe alternatives you've considered
I've slapped together a first draft for your consideration. We can consider this proof of concept. Open to considerable feedback :) I wanted to learn mkdocs and i considered your excellent documentation a worthy test case.

Additional context
The solution I've come up with so far is completely automated. The script i created parses the current README.md and breaks each h1 header into a new page in mkdocs. Furthermore, i pull in the mergerfs wiki .md files as well as the mergerf-tools README.md, since i think they are all related, and IMO, doesn't hurt to have them together in a single site.

I'm currently using GH pages to test it. It would be possible to have the documentation re-built automatically on changes to any of the aforementioned repositories (mergerfs/wiki/mergerfs-tools), if this concept is agreeable to you.

Ideally, i think it would be great if the README.md for this project could be split up in separate files much like the wiki, because this would make it easier to automate into mkdocs (the automation script i created could be significantly smaller).

broken links:

• There are a few broken links in the documentation which could be remedied by switching to absolute links in the official README.md instead of relative links.

Here is the proof of concept --> https://oregonpillow.github.io/

i only plan to host it on GH Pages temporarily as I'm generally not a fan of GH pages, and despise the fact that GH pages makes you host at the profile level and not at the project level. I hope this is ok for now. Tell me if it isn't and i'll remove it.

[oregonpillow]

corresponding forked repository: https://github.com/oregonpillow/oregonpillow.github.io

[trapexit]

Awesome. Thank you so much. Yes, it's been on my todo list for probably years now but never got around to it.

I just got home from holiday so I won't get a chance to look at this in detail for a day or so but a quick glance it looks like a good start. I think it will need to be reformated for the style of the docs. Probably some more walkthrough. I'll need to read up on mkdocs to understand what is possible.

For instance the FAQ... I wonder what options are there for that to make it less a big wall of text. Should it be it's own section on the left or whatnot.

In the meantime feel free to tweak to whatever you feel is good. I'll spend some time on learning mkdocs and I'd be happy to take a PR even with just some basic variant of what you have now.

[oregonpillow]

Ok great, and no worries take your time. I'll see if I can clean things up abit and see if other settings in mkdocs might help with faq. Thanks for the support.

[oregonpillow]

So I had another look at things, I'm personally not a fan of using the script I wrote to convert the existing README into separate pages. It was fun writing but it complicates things and is something extra to maintain. It also becomes more complicated becomes it pulls in additional markdown files from the WIKI + mergerfs-tools repositories. Basically, it's not a long term sustainable solution.

For maintainability, the best way to maintain docs for mkdocs (or any other site generator) is simply to store the markdown files in the structure you want e,g /mkdocs/docs/....

However this means the current README.md will become redundant when we copy the contents from it.

Here is what i propose:

1. split the current README.md into separate markdown pages under mkdocs/docs/
2. After step 1 is complete, the current README.md is significantly shortened, keeping only a high level overview of mergerfs and linking to the new documentation site for more information.
3. move the wiki markdown files out of the mergerfs wiki and also move these under mkdocs/docs/
4. For mergerfs-tools, i don't think it warrants it's own mkdocs page, therefore the mergerfs-tools/README stays where it is. We'll simply reference to this repository within the mkdocs site.

Hosting plans?
What would be the new hosting location for mkdocs? Keeping it on GitHub Pages? I saw you already use https://trapexit.github.io/, what about hosting mkdocs with GitHub pages BUT getting mergerfs it's own domain site for the documentation site? e.g. mergerfs.wiki?

[oregonpillow]

Once we have a plan of action, then i think it would be clear what I could include within a PR

[trapexit]

Oh, sorry, I had no intention to keep the README as it is when adding mkdocs or similar. It would become much simpler.

I'm not really using trapexit.github.io. I was playing with that years ago. I have my own domain over at https://spawn.link. I could pretty easily setup mergerfs.spawn.link or even just use trapexit.github.io. And then if I get so motivated could grab a domain.

[oregonpillow]

Oh no worries at all, it's actually my fault for not clarifying!

I think i'm at the point now where i would feel ok submitting a first draft for review, i've fixed the links and put the FAQ into it's own section which is more readable now --> https://oregonpillow.github.io/

I guess the easiest option to immediately test would to use your trapexit.github.io, because it should be a 1:1 replacement of the way it's currently deployed for me.

Current Deployment method

In my branch https://github.com/oregonpillow/oregonpillow.github.io , you'll see there are 2 branches. When changes are detected on the latest-release branch , GH actions rebuilds the mkdocs site and pushes the static site --> gh-pages branch which is where GH pages serves from.

In order for this to work these are the changes i had to make:

1. Create environment

2. Environment settings

3. GH Pages settings

however, this means your https://github.com/trapexit/trapexit.github.io will become the mergerfs docs site, therefore i should be opening a PR against that project. Do you agree? Or does this make sense? I will also need to remove all the non mkdocs directories that i got when i forked this project, since we're only pushing mkdocs related files.