Move documentation to a docs site for navigability and accessibility

[ChipWolf]

Enhancement Type

Not sure

Describe the enhancement

With the size the readme has become, it would benefit from becoming a micro-site using Mkdocs or similar.
This would be more scalable, accessible, and allow for better navigation between key concepts and features.

[itzg]

I like the look of this one and use of markdown: https://squidfunk.github.io/mkdocs-material/

[itzg]

@camalot thought I'd bring our conversation over here.

I'm now thinking a Jekyll based site generator would be ideal since that'll plug into GitHub pages without additional build support

https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#static-site-generators

[itzg]

...and taking a few more minutes to read, I see that using custom site generators are fairly simple:

https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow

[camalot]

Looks like this https://github.com/marketplace/actions/deploy-mkdocs can be used to directly deploy an MkDocs site directly to github pages with the material theme.

[camalot]

Quick little test: https://camalot.github.io/mkdocs-test/ in this repo https://github.com/camalot/mkdocs-test

[itzg]

That looks great @camalot ! I think we should go with that. The only I'm left pondering is how to transition over.

A few sections at a time leaving major headers as a link over to new docs?

Do the whole thing at once with each major section as a "page" and then have one big link at the top that says where to find docs?

[camalot]

Shouldn't take too long to do in initial convert. I have been taking each "Heading2" and making those into "pages" in this test repo.

Maybe leave original readme there with a link to the docs indicating the transition, and that the doc site may be incomplete, so refer to the readme.

Can probably better organize the "pages" too, by "edition" or something. then you could technically have bedrock docs there too.

example, I created docs/deployment and that has files for helm, aws, docker-compose and they are then referenced in the nav like this:

    - "Deployment Templates and Examples":
      - "Helm Charts": "deployment/helmcharts.md"
      - "Amazon Web Services (AWS)": "deployment/aws.md"
      - "Docker Compose": "deployment/docker-compose.md"

which renders as

I also just figured out that you can do the following in the navigation

 - "Related Projects":
    - related-projects.md
    - "itzg/minecraft-bedrock-server": https://github.com/itzg/docker-minecraft-bedrock-server
    - "mc-router": https://github.com/itzg/mc-router
    - "itzg/bungeecord": https://github.com/itzg/docker-bungeecord/
    - "itzg/mc-backup": https://github.com/itzg/docker-mc-backup
    - "rcon-cli": https://github.com/itzg/rcon-cli
    - "mc-monitor": https://github.com/itzg/mc-monitor
    - "mc-image-helper": https://github.com/itzg/mc-image-helper
    - "itzg/rcon": https://github.com/itzg/docker-rcon-web-admin

Which renders the following:

There is a "related-projects.md" file which has the descriptions and links, but in the navigation, they are also direct links.

[camalot]

I think i have all the "README" in that test site. now would just need a repo for the actual docs, and then the "layout" and files could be modified after.

[camalot]

changes to the doc files could be things that would make use of the Admonitions in the mkdocs-material theme, in stead of relying upon the basic github markdown

[itzg]

Those admonitions are perfect! Needed those for things like the importance of having a CF_API_KEY.

Hmm, any suggestions for the overall docs repo name?

Some ones I'm thinking aren't terribly excited but track with the names of image repos

• minecraft-on-docker
• minecraft-docker
• docker-minecraft

[camalot]

Any of those might actually work well. because if someone searches for those phrases, the documentation might come back. which in turn will give them the info they need on how to run it. and then if they run in to issues, they can report in this (or related) repo.

[camalot]

Will have to grant this permission in the docs repo so it can push to the gh-pages branch. (might also have to do this for the action to push to the GHCR too)

[camalot]

I curated a list of variables that can be set. a "cheat sheet", versus trying to hunt down the environment variables. There are more to add.

https://camalot.github.io/mkdocs-test/java/environment/

[itzg]

I curated a list of variables that can be set. a "cheat sheet", versus trying to hunt down the environment variables. There are more to add.

Awesome! I always wanted to write a tool that would pick those out of the defaults/usage. Now, I just broke that pattern with CF_API_KEY, which is directly consumed by mc-image-helper, here. I should probably put an empty "declaration" like

: ${CF_API_KEY=}

Would that help this kind of analysis?

[camalot]

I was just going through the readme and looked at the dockerfile.

…

On Sat, Apr 1, 2023, 4:56 PM Geoff Bourne ***@***.***> wrote: I curated a list of variables that can be set. a "cheat sheet", versus trying to hunt down the environment variables. There are more to add. Awesome! I always wanted to write a tool that would pick those out of the defaults/usage. Now, I just broke that pattern with CF_API_KEY, which is directly consumed by mc-image-helper, such as <https://github.com/itzg/mc-image-helper/blob/e0b69537c6a8d8d349f7b0057eb0d823832a62fe/src/main/java/me/itzg/helpers/curseforge/InstallCurseForgeCommand.java#L53-L57>. I should probably put an empty "declaration" like : ${CF_API_KEY=} Would that help this kind of analysis? — Reply to this email directly, view it on GitHub <#1440 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABJ3PGKSNFZSQQEMSQ7HHLW7CQBLANCNFSM5TUMPLNQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[itzg]

I got a repo setup, enabled github pages using github actions, and adjusted the GITHUB_TOKEN access:

https://github.com/itzg/docker-minecraft-docs

[camalot]

I could probably write something that scrapes some files or something. but it wouldnt have the descriptions.

I'll pull that repo and get an initial commit to it.

[camalot]

you might have to create a gh-pages branch, and have gh-pages publish from that.

[itzg]

you might have to create a gh-pages branch, and have gh-pages publish from that.

Ah yes, I was wondering if being a github actions style it could generate from the main branch, but I can also create a gh-pages branch to be sure.

[itzg]

Done: https://github.com/itzg/docker-minecraft-docs/tree/gh-pages

[camalot]

Mkdocs supports versioning too. so it will be possible, in theory, to "tag" the changes based on the server version, and have docs based on the version.

I'm not entirely sure how that works, but I read that you can do it in their docs.

[itzg]

By server version, what were you thinking exactly? The Minecraft version like 1.19.4 or the image tagged version? I'm suspecting either or another might be overkill.

[camalot]

i would say maybe when some type of ENV VAR changes, that would be a good time for a "doc tag", since it wouldnt work with image-tag before that version.

For example, the CF_API_KEY change, wasn't needed before the change the other day.

It was just a thought, not sure if it would be really practical or not.

[camalot]

First PR for the changes are here itzg/docker-minecraft-docs#1

[itzg]

I didn't realize this issue was still open even the docs site has been going for a little while.