From 59e2b9c636a6c9daf2323f1e710fe58d23c6079d Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 26 Jul 2020 14:46:09 +0200 Subject: [PATCH] Fixed errors in documentation --- docs/changelog.md | 4 +- docs/getting-started.md | 25 +++-- docs/reference/code-blocks.md | 2 +- docs/reference/icons-emojis.md | 41 +++++-- docs/setup/adding-a-comment-system.md | 1 + docs/setup/adding-a-git-repository.md | 2 +- docs/setup/adding-social-links.md | 2 +- docs/setup/changing-the-colors.md | 12 +- docs/setup/changing-the-fonts.md | 2 +- docs/setup/changing-the-language.md | 5 +- docs/setup/changing-the-logo-and-icons.md | 4 +- docs/setup/setting-up-navigation.md | 14 +-- docs/setup/setting-up-site-analytics.md | 10 +- docs/setup/setting-up-site-search.md | 25 +++-- docs/sponsorship.md | 130 +++++++++++++--------- 15 files changed, 161 insertions(+), 118 deletions(-) diff --git a/docs/changelog.md b/docs/changelog.md index 376936294..9c8ff97a6 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -4,7 +4,7 @@ template: overrides/main.html # Changelog -## Sponsor edition +## Material for MkDocs Insiders ### 1.0.0 _ July 14, 2020 @@ -12,7 +12,7 @@ template: overrides/main.html * Added missing query terms to search result * Improved search result relevance and scoring -## Community edition +## Material for MkDocs ### 5.5.0 _ July 24, 2020 diff --git a/docs/getting-started.md b/docs/getting-started.md index 4e9dcd5df..3916885a9 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -5,7 +5,7 @@ template: overrides/main.html # Getting started Material for MkDocs is a theme for [MkDocs][1], a static site generator geared -towards (technical) project documentation. If you're familar with Python, you +towards (technical) project documentation. If you're familiar with Python, you can install Material for MkDocs with [`pip`][2], the Python package manager. If not, we recommended using [`docker`][3]. @@ -22,16 +22,16 @@ In case you're running into problems, consult the [troubleshooting][4] section. Material for MkDocs can be installed with `pip`: -=== "Community edition" +=== "Material for MkDocs" ``` pip install mkdocs-material ``` -=== "Sponsor edition" +=== "Material for MkDocs Insiders" ``` sh - pip install git+https://$GH_TOKEN@github.com/squidfunk/mkdocs-material-next.git + pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git ``` This will automatically install compatible versions of all dependencies: @@ -39,9 +39,9 @@ This will automatically install compatible versions of all dependencies: Material for MkDocs always strives to support the latest versions, so there's no need to install those packages separately. -Note that in order to install the [sponsor edition][8], you'll need to [become -a sponsor][9], create a [personal access token][10], and set the `GH_TOKEN` -environment variable to the token's value. +Note that in order to install [__Material for MkDocs Insiders__][8], you'll +need to [become a sponsor][9], create a [personal access token][10], and set +the `GH_TOKEN` environment variable to the token's value. [5]: https://python-markdown.github.io/ [6]: https://pygments.org/ @@ -61,7 +61,7 @@ docker pull squidfunk/mkdocs-material ``` The `mkdocs` executable is provided as an entry point and `serve` is the -default command. If you're not familar with Docker don't worry, we have you +default command. If you're not familiar with Docker don't worry, we have you covered in the following sections. [11]: https://hub.docker.com/r/squidfunk/mkdocs-material/ @@ -72,16 +72,16 @@ Material for MkDocs can be directly used from [GitHub][12] by cloning the repository into a subfolder of your project root which might be useful if you want to use the very latest version: -=== "Community edition" +=== "Material for MkDocs" ``` git clone https://github.com/squidfunk/mkdocs-material.git ``` -=== "Sponsor edition" +=== "Material for MkDocs Insiders" ``` - git clone git@github.com:squidfunk/mkdocs-material-next.git mkdocs-material + git clone git@github.com:squidfunk/mkdocs-material-insiders.git mkdocs-material ``` The theme will reside in the folder `mkdocs-material/material`. Note that when @@ -91,4 +91,7 @@ cloning from `git`, you must install all required dependencies yourself: pip install -r mkdocs-material/requirements.txt ``` +Note that in order to install [__Material for MkDocs Insiders__][8], you'll +need to [become a sponsor][9]. + [12]: https://github.com/squidfunk/mkdocs-material diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md index 929890b69..e99b86b78 100644 --- a/docs/reference/code-blocks.md +++ b/docs/reference/code-blocks.md @@ -285,7 +285,7 @@ The `#!python range()` function is used to generate a sequence of numbers. When [Keys][19] is enabled, keyboard keys can be rendered with a simple syntax. Consult the [Python Markdown Extensions][16] documentation to learn about all -available short key codes. +available key codes. _Example_: diff --git a/docs/reference/icons-emojis.md b/docs/reference/icons-emojis.md index 7dc997613..f5794491c 100644 --- a/docs/reference/icons-emojis.md +++ b/docs/reference/icons-emojis.md @@ -46,13 +46,26 @@ about configuration options. [8]: https://octicons.github.com/ [9]: ../setup/changing-the-logo-and-icons.md#additional-icons +### Attribute Lists + +The [Attribute List][10] extension, which is part of the standard Markdown +library, allows to __add HTML attributes and classes to Markdown elements__, +and can be enabled via `mkdocs.yml` + +``` yaml +markdown_extensions: + - attr_list +``` + + [10]: https://python-markdown.github.io/extensions/attr_list/ + ## Usage ### Using emojis Emojis can be integrated in Markdown by putting the shortcode of the emoji -between two colons. If you're using [Twemoji][10] (recommended), you can look up -the shortcodes at [Emojipedia][11]. +between two colons. If you're using [Twemoji][11] (recommended), you can look up +the shortcodes at [Emojipedia][12]. _Example_: @@ -64,12 +77,12 @@ _Result_: :smile: - [10]: https://twemoji.twitter.com/ - [11]: https://emojipedia.org/twitter/ + [11]: https://twemoji.twitter.com/ + [12]: https://emojipedia.org/twitter/ ### Using icons -When [Emoji][12] is enabled, icons can be used similar to emojis, by referencing +When [Emoji][13] is enabled, icons can be used similar to emojis, by referencing a valid path to any icon bundled with the theme, which are located in the [`.icons`][1] directory, and replacing `/` with `-`: @@ -83,11 +96,15 @@ _Example_: _Result_: -* :material-account-circle: – [`.icons/material/account-circle.svg`][13] -* :fontawesome-regular-laugh-wink: – [`.icons/fontawesome/regular/laugh-wink.svg`][14] -* :octicons-octoface-16: – [`.icons/octicons/octoface-16.svg`][15] +* :material-account-circle: – [`.icons/material/account-circle.svg`][14] +* :fontawesome-regular-laugh-wink: – [`.icons/fontawesome/regular/laugh-wink.svg`][15] +* :octicons-octoface-16: – [`.icons/octicons/octoface-16.svg`][16] - [12]: #emoji - [13]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/material/account-circle.svg - [14]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/fontawesome/regular/laugh-wink.svg - [15]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/octicons/octoface-16.svg + [13]: #emoji + [14]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/material/account-circle.svg + [15]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/fontawesome/regular/laugh-wink.svg + [16]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/material/.icons/octicons/octoface-16.svg + +### Using colored icons + +### Using animated icons diff --git a/docs/setup/adding-a-comment-system.md b/docs/setup/adding-a-comment-system.md index c2edc9d74..22766ada5 100644 --- a/docs/setup/adding-a-comment-system.md +++ b/docs/setup/adding-a-comment-system.md @@ -1,5 +1,6 @@ --- template: overrides/main.html +disqus: mkdocs material --- # Adding a comment system diff --git a/docs/setup/adding-a-git-repository.md b/docs/setup/adding-a-git-repository.md index 6abfd05ae..a6e922231 100644 --- a/docs/setup/adding-a-git-repository.md +++ b/docs/setup/adding-a-git-repository.md @@ -6,7 +6,7 @@ template: overrides/main.html If your documentation is related to source code, Material for MkDocs provides the ability to display information to the project's repository as part of the -static site, including statistics like stars and forks. Furthermore, certain +static site, including statistics like stars and forks. Furthermore, individual documents can be linked to specific source files. ## Configuration diff --git a/docs/setup/adding-social-links.md b/docs/setup/adding-social-links.md index e1de066b6..bd4078a59 100644 --- a/docs/setup/adding-social-links.md +++ b/docs/setup/adding-social-links.md @@ -4,7 +4,7 @@ template: overrides/main.html # Adding social links -The footer of your project documentation is a good place to add links to +The footer of your project documentation is a great place to add links to websites or platforms you or your company are using as additional marketing channels, e.g. :fontawesome-brands-medium:{: style="color: #00AB6C" }, :fontawesome-brands-twitter:{: style="color: #1DA1F2" } or diff --git a/docs/setup/changing-the-colors.md b/docs/setup/changing-the-colors.md index d6f8849d6..376eac19e 100644 --- a/docs/setup/changing-the-colors.md +++ b/docs/setup/changing-the-colors.md @@ -4,7 +4,7 @@ template: overrides/main.html # Changing the colors -As any good Material Design implementation, Material for MkDocs supports +As any proper Material Design implementation, Material for MkDocs supports Google's original [color palette][1], which can be easily configured through `mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to fit your brand's identity by using [CSS variables][2]. @@ -28,7 +28,7 @@ theme: scheme: default ``` -:material-cursor-default-click-outline: click on a tile to change the color +:material-cursor-default-click-outline: Click on a tile to change the color scheme:
@@ -74,7 +74,7 @@ theme: primary: indigo ``` -:material-cursor-default-click-outline: click on a tile to change the primary +:material-cursor-default-click-outline: Click on a tile to change the primary color:
@@ -121,7 +121,7 @@ color: The _accent color_ is used to denote elements that can be interacted with, e.g. hovered links, buttons and scrollbars. It can be changed in `mkdocs.yml` by -chosing a valid color name: +choosing a valid color name: ``` yaml theme: @@ -129,7 +129,7 @@ theme: accent: indigo ``` -:material-cursor-default-click-outline: click on a tile to change the accent +:material-cursor-default-click-outline: Click on a tile to change the accent color: