From 55741dbfa8521722e49307a2dc8a976d5c8d0e41 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Fri, 24 Jul 2020 14:30:03 +0200 Subject: [PATCH] Added syntax theme customization guide --- docs/reference/code-blocks.md | 46 ++++++++++++++++++++++--- docs/setup/adding-social-links.md | 2 +- docs/setup/changing-the-colors.md | 4 +-- docs/setup/setting-up-site-analytics.md | 2 +- docs/sponsorship.md | 2 +- 5 files changed, 47 insertions(+), 9 deletions(-) diff --git a/docs/reference/code-blocks.md b/docs/reference/code-blocks.md index 81ef6122f..e04c285f5 100644 --- a/docs/reference/code-blocks.md +++ b/docs/reference/code-blocks.md @@ -332,9 +332,47 @@ explained in the [official documentation][16]. [:octicons-file-code-24: Source][21] · :octicons-mortar-board-24: Difficulty: _easy_ -If syntax highlighting is done with [Pygments][22], Material for MkDocs -provides the styles defining the [appeareance][21] of code blocks, which can -be adjusted with [additional stylesheets][6]. +If [Pygments][22] is used, Material for MkDocs provides the [styles for code +blocks][21], which are built with a custom and well-balanced palette that works +equally well for both [color schemes][23]: - [21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_codehilite.scss +- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-number-color) " } `--md-code-hl-number-color` +- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-special-color) " } `--md-code-hl-special-color` +- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-function-color) " } `--md-code-hl-function-color` +- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-constant-color) " } `--md-code-hl-constant-color` +- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-keyword-color) " } `--md-code-hl-keyword-color` +- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-string-color) " } `--md-code-hl-string-color` +- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-name-color) " } `--md-code-hl-name-color` +- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-operator-color) " } `--md-code-hl-operator-color` +- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-punctuation-color) " } `--md-code-hl-punctuation-color` +- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-comment-color) " } `--md-code-hl-comment-color` +- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-generic-color) " } `--md-code-hl-generic-color` +- :material-checkbox-blank-circle:{: style="color: var(--md-code-hl-variable-color) " } `--md-code-hl-variable-color` + +Let's say you want to change the color of `#!js "strings"`. While there are +several [types of string tokens][24], Material for MkDocs assigns a single color +to most of them. + +Add an [additional stylesheet][6], and add: + +``` css +:root { + --md-code-hl-string-color: #0FF1CE; +} +``` + +If you want to tweak a specific type of string, i.e. ``#!js `backticks` ``, you +can lookup the specific class name in the [syntax theme definition][25], and +override it as part of your additional stylesheet: + +``` css +.highlight .sb { + color: #0FF1CE; +} +``` + + [21]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss#L60-L73 [22]: #use-pygments + [23]: ../setup/changing-the-colors.md#color-scheme + [24]: https://pygments.org/docs/tokens/#literals + [25]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/markdown/_codehilite.scss#L42 diff --git a/docs/setup/adding-social-links.md b/docs/setup/adding-social-links.md index 4cffe0c23..e1de066b6 100644 --- a/docs/setup/adding-social-links.md +++ b/docs/setup/adding-social-links.md @@ -96,7 +96,7 @@ For each entry, the following fields are available: [:octicons-file-code-24: Source][2] · :octicons-mortar-board-24: Difficulty: _moderate_ -The social links feature uses the available [icon integration][3] of Material for +The social links feature uses the standard [icon integration][3] of Material for MkDocs. If you want to use custom icons, follow the guide explaining how to add [additional icons][4]. diff --git a/docs/setup/changing-the-colors.md b/docs/setup/changing-the-colors.md index 782f3ad52..d6f8849d6 100644 --- a/docs/setup/changing-the-colors.md +++ b/docs/setup/changing-the-colors.md @@ -195,7 +195,7 @@ use your brand-specific colors), you can add an [additional stylesheet][8] and tweak the values of the CSS variables. Let's say you're :fontawesome-brands-youtube:{: style="color: #EE0F0F" } -__YouTube__, and want to set the primary color to your brand's palette, just +__YouTube__, and want to set the primary color to your brand's palette. Just add: ``` css @@ -220,7 +220,7 @@ variables. :octicons-mortar-board-24: Difficulty: _easy_ Besides overriding specific colors, you can create your own, named color scheme -by wrapping the definitions in the `[data-md-color-scheme="..."]` +by wrapping the definitions in the `#!css [data-md-color-scheme="..."]` [attribute selector][9], which you can then set via `mkdocs.yml` as described in the [color schemes][10] section: diff --git a/docs/setup/setting-up-site-analytics.md b/docs/setup/setting-up-site-analytics.md index 77b609d16..b826cc3d3 100644 --- a/docs/setup/setting-up-site-analytics.md +++ b/docs/setup/setting-up-site-analytics.md @@ -31,7 +31,7 @@ google_analytics: [3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/analytics.html [4]: https://support.google.com/analytics/answer/1042508 -#### Enabling site search tracking +#### Site search tracking Besides basic page views, _site search_ can also be tracked to better understand how people use your documentation and what they expect to find. To enable diff --git a/docs/sponsorship.md b/docs/sponsorship.md index 94b1b03a5..dfe7c349a 100644 --- a/docs/sponsorship.md +++ b/docs/sponsorship.md @@ -114,7 +114,7 @@ the following guidelines: - If you cancel your subscription, you're removed as a collaborator and will not receive future updates of the sponsor edition. However, you may continue to - use the latest version that's available to you for __as long as you like__. + __use the latest version__ that's available to you __as long as you like__. Just remember that __[GitHub deletes private forks][13]__. [12]: license.md