From b6cd73e08360687149d13e4769c61fd2857cdbf3 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 10 Oct 2021 12:19:14 +0200 Subject: [PATCH] Updated documentation --- docs/customization.md | 2 +- docs/insiders/getting-started.md | 32 ++-- docs/reference/abbreviations.md | 4 +- docs/reference/admonitions.md | 82 +++++----- docs/reference/buttons.md | 16 +- docs/reference/code-blocks.md | 55 ++++--- docs/reference/content-tabs.md | 12 +- docs/reference/data-tables.md | 4 +- docs/reference/diagrams.md | 6 +- docs/reference/footnotes.md | 14 +- docs/reference/formatting.md | 21 ++- docs/reference/icons-emojis.md | 151 ++++++++++-------- docs/reference/images.md | 62 ++++--- docs/reference/lists.md | 122 +++++--------- docs/reference/mathjax.md | 67 +++----- docs/setup/adding-a-git-repository.md | 6 +- docs/setup/changing-the-colors.md | 2 +- docs/setup/changing-the-fonts.md | 2 +- .../extensions/python-markdown-extensions.md | 42 +++-- docs/setup/extensions/python-markdown.md | 9 +- docs/setup/setting-up-navigation.md | 28 ++-- docs/setup/setting-up-site-analytics.md | 22 +-- docs/setup/setting-up-site-search.md | 22 +-- docs/setup/setting-up-social-cards.md | 12 +- docs/setup/setting-up-tags.md | 2 +- docs/setup/setting-up-versioning.md | 10 +- mkdocs.yml | 2 +- 27 files changed, 407 insertions(+), 402 deletions(-) diff --git a/docs/customization.md b/docs/customization.md index 36974c3ed..90a6b598b 100644 --- a/docs/customization.md +++ b/docs/customization.md @@ -39,7 +39,7 @@ extra_css: ``` Spin up the [live preview server][2] and start typing your changes in your -additional stylesheet file – you should see them almost instantly after saving. +additional style sheet file – you should see them almost instantly after saving. [2]: creating-your-site.md#previewing-as-you-write diff --git a/docs/insiders/getting-started.md b/docs/insiders/getting-started.md index a3a60f391..da5ca4e79 100644 --- a/docs/insiders/getting-started.md +++ b/docs/insiders/getting-started.md @@ -21,10 +21,10 @@ In order to access the Insiders repository programmatically (from the command line or GitHub Actions workflows), you need to create a [personal access token][4]: -1. Go to https://github.com/settings/tokens -2. Click on [Generate a new token][5] -3. Enter a name and select the [`repo`][6] scope -4. Generate the token and store it in a safe place +1. Go to https://github.com/settings/tokens +2. Click on [Generate a new token][5] +3. Enter a name and select the [`repo`][6] scope +4. Generate the token and store it in a safe place [4]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token [5]: https://github.com/settings/tokens/new @@ -52,18 +52,18 @@ additional steps are necessary. While we cannot provide a hosted Docker image for Insiders[^1], [GitHub Container Registry][7] allows for simple and comfortable self-hosting: -1. [Fork the Insiders repository][8] -2. Enable [GitHub Actions][9] on your fork[^2] -3. Create a new personal access token[^3] - 1. Go to https://github.com/settings/tokens - 2. Click on [Generate a new token][5] - 3. Enter a name and select the [`write:packages`][10] scope - 4. Generate the token and store it in a safe place -4. Add a [GitHub Actions secret][11] on your fork - 1. Set the name to `GHCR_TOKEN` - 2. Set the value to the personal access token created in the previous step -5. [Create a new release][12] to build and publish the Docker image -6. Install [Pull App][13] on your fork to stay in-sync with upstream +1. [Fork the Insiders repository][8] +2. Enable [GitHub Actions][9] on your fork[^2] +3. Create a new personal access token[^3] + 1. Go to https://github.com/settings/tokens + 2. Click on [Generate a new token][5] + 3. Enter a name and select the [`write:packages`][10] scope + 4. Generate the token and store it in a safe place +4. Add a [GitHub Actions secret][11] on your fork + 1. Set the name to `GHCR_TOKEN` + 2. Set the value to the personal access token created in the previous step +5. [Create a new release][12] to build and publish the Docker image +6. Install [Pull App][13] on your fork to stay in-sync with upstream The [`publish`][14] workflow[^4] is automatically run when a new tag (release) is created. When a new Insiders version is released on the upstream repository, diff --git a/docs/reference/abbreviations.md b/docs/reference/abbreviations.md index 608b45a40..49a8454dc 100644 --- a/docs/reference/abbreviations.md +++ b/docs/reference/abbreviations.md @@ -4,7 +4,7 @@ template: overrides/main.html # Abbreviations -Technical documentation often incurs the usage of a lot of acronyms, which may +Technical documentation often incurs the usage of many acronyms, which may need additional explanation, especially for new user of your project. For these matters, Material for MkDocs uses a combination of Markdown extensions to enable site-wide glossaries. @@ -69,7 +69,7 @@ all abbreviations in a dedicated file[^1], and embedding it with the _Example_: -=== ":octicons-file-code-16: docs/page.md" +=== ":octicons-file-code-16: docs/example.md" ```` markdown The HTML specification is maintained by the W3C. diff --git a/docs/reference/admonitions.md b/docs/reference/admonitions.md index 035637e52..3114fccfa 100644 --- a/docs/reference/admonitions.md +++ b/docs/reference/admonitions.md @@ -404,37 +404,9 @@ the default type, and thus fallback for unknown type qualifiers, is `note`: ### Custom admonitions -[:octicons-file-code-24: Source][Source] · -:octicons-mortar-board-24: Difficulty: _easy_ - If you want to add a custom admonition type, all you need is a color and an -`*.svg` icon. Copy the icon's code from the [`.icons`][Custom icons] folder -and add the following CSS to an [additional stylesheet]: - -``` css -:root { - --md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,') -} -.md-typeset .admonition.pied-piper, -.md-typeset details.pied-piper { - border-color: rgb(43, 155, 70); -} -.md-typeset .pied-piper > .admonition-title, -.md-typeset .pied-piper > summary { - background-color: rgba(43, 155, 70, 0.1); - border-color: rgb(43, 155, 70); -} -.md-typeset .pied-piper > .admonition-title::before, -.md-typeset .pied-piper > summary::before { - background-color: rgb(43, 155, 70); - -webkit-mask-image: var(--md-admonition-icon--pied-piper); - mask-image: var(--md-admonition-icon--pied-piper); -} -``` - -You should now be able to create an admonition of the `pied-piper` type. Note -that you can also use this technique to override existing admonition icons or -colors. [You can even add animations][Custom animations]. +`*.svg` icon. Copy the icon's code from the [`.icons`][custom icons] folder +and add the following CSS to an [additional style sheet]: