update contribution guidelines for docs

[CouldBeThis]

• [ ] structure of repo + relationship to rest of project
• [ ] most relevant tools, how they are used + links to useful docs
  • [ ] mkdocs,
  • [ ] markdown,
  • [ ] git + github - source management,
  • [ ] github - issue tracking + discussion
• [ ] styleguide (DietPi vs dietpi etc)
• [ ] how/why to use linter prior to submitting PR,

little weirdies

• [ ] the headings vs font in tabs situation #446
• [ ] discrepancies between md display on github vs in mkdocs

I actually started this a bit already. (Those who can't do, teach.)

**

Am not sure exactly where it might live. On repos' readmes there are https://github.com/MichaIng/DietPi#contributing and https://github.com/MichaIng/DietPi-Docs#contributing A separate file might be better? Some of it might be useful to the rest of the project but mostly it would be too basic.

please add

• if you can think of anything that would be helpful.
• if there are any old discussions that would be important background info.

I will add as I come across things.

[MichaIng]

Many thanks for your suggestions.

Good points. It makes sense to make clear on each repository what it is for, and add that to our contribution page and/or the docs.

• As everything is Git(Hub), link a nice intro for that. I actually got a nice open-source GitHub/Git guide some time ago on Twitter, I'll try to dig that out again.
• For the docs repo, add info that all content is written in Markdown and converted via MkDocs (mentioned already in the README) and link basic Markdown and MkDocs syntax/docs. Probably even an info about the used Markdown extensions could be added. Links to the extension docs probably fit best into the mkdocs.yml directly, as common aside/above each extension.

As for the linter, when cloning the repo within GitHub, one just needs to enable GitHub actions for the own repo (I think that is not the case by default). Since the actions config is part of the repo, it should then run automatically on each commit: https://github.com/MichaIng/DietPi-Docs/blob/master/.github/workflows/actions.yml

That is not true for CodeFactor checks, which is an app that requires an account. But we might convert that into GitHub actions as well, to have everything in one place.

[StephanStS]

Regarding the linter (Markdown checker)

What should I do before issueing a PR? If you generate an own branch for developing DietPi-Docs you are able to run the checks before issueing the PR. Just push your changes to your (private) branch and then go to the "actions" tab:

Then, select the "..." and "View workflow file" which belongs to your push operation:

Then, click on "Actions" and examine the output of the checks:

Remarks:

• Markdown lint messages have typically corrected by editing the appropriate .md file
• PySpelling messages may lead to textual changes in the .md files, or can lead to additions in the .wordlist.txt file (located in the docs root directory).
• Take into account that in the link check ("Run liche...") there may occur timeouts.

[StephanStS]

Regarding editing Markdown

Here we may collect some useful hints for editing the Markdown files.

Admonitions

If you want to use admonitions: See mkdocs reference.
Examples for admonitions (in file https://dietpi.com/docs/install):

Keyboard keys

If you want to use keyboard keys, see PyMdown Extension docu and mkdocs reference.
Examples for keys (in file https://dietpi.com/docs/dietpi_tools/):