WIP – Restructure documentation

[squidfunk]

This PR is a WIP to restructure Material for MkDocs's documentation. The user survey revealed that people still have trouble setting up and customizing Material for MkDocs. The aim of this work is to rewrite the docs to be more user- and solution-oriented instead of just listing all possible configuration options. It should also give better guidance on the whole process of writing docs: from creation to deployment.

[netlify]

Deploy preview for mkdocs-material-preview ready!

Built with commit a85f182

https://deploy-preview-1735--mkdocs-material-preview.netlify.app

[Andre601]

Do you already have a general structure of the pages and what they should contain? I could help moving some of the pages to the new ones.

[squidfunk]

Yes, the structure for the guides is already in-place, as can be seen in the preview. Copying isn't enough though, a lot of stuff needs to be rewritten and amended.

[Andre601]

The example of GitHub Actions is imo a bit bad.
Why have pull_request as a possible trigger when you later check for if it isn't a pull request and the head points to master?

When the action should only trigger on pushes towards the master branch would this here be sufficient enough:

on:
  push:
    branches:
    - master

[facelessuser]

I don't think it's bad per se, maybe for deployment, it makes a little less sense, but I think it is trying to illustrate the ways in which you can adapt it for different things. I don't deploy except when I tag a release, but I do run mkdocs on pulls by running it in strict mode to catch issues and to generate the docs which I then run my spellchecker on.

[squidfunk]

@Andre601 thanks! That's a valid concern. The aim is to make it as concise as possible. I added your suggestion in b652bda.

[Andre601]

I think it would be good to mention, that the published pages would be available at <username.github.io OR any custom subdomain you defined as described in the MkDocs doc (maybe link to it?)

I, in general, mean to change

Your documentation should shortly appear at `<username>.github.io/<repository>`.

to

Your documentation should shortly appear at `<username>.github.io/<repository>` or under a specified CNAME as described in [MkDocs' documentation][n].

[n]: https://www.mkdocs.org/user-guide/deploying-your-docs/#custom-domains

or something similar.similar.

[squidfunk]

@Andre601 I think if somebody knows how to publish documentation under GitHub pages, the person should also know that when a custom domain name is set, the URL is different. I'd rather leave it as an exercise to the reader for now, as it may confuse other users.

[Andre601]

Fair enough.

About that sponsor thing... Are those goals dynamic, or is it like "staying" at what the current amount is?
Like would one goal become locked again once the goal isn't reached anymore, or would it stay open even if the funding becomes less?

[squidfunk]

About that sponsor thing... Are those goals dynamic, or is it like "staying" at what the current amount is?
Like would one goal become locked again once the goal isn't reached anymore, or would it stay open even if the funding becomes less?

Once it's released, it's released, so in the case that for example $ 500 is reached, and then all sponsors would cut their sponsoring, the feature will stay in the community edition :-) I will add something to clear that up!

[Andre601]

I btw wanted to mention, that using Dark reader on your landing page makes it look really funny (It imo looks cool that way)

[squidfunk]

That looks weird. I added some styles that invert the white wave when slate is set – maybe it solves the problem:

[Andre601]

Wasn't really a problem for me. It looked kinda cool