From 06608e98a779cbcc4d037dcec6f25c9d2cc02499 Mon Sep 17 00:00:00 2001
From: Waylan Limberg <waylan.limberg@icloud.com>
Date: Tue, 17 Jul 2018 14:41:55 -0400
Subject: [PATCH] Add hljs_style config to mkdocs theme.

This is primarily to allow third party themes which inherit from the
mkdocs theme (such as the bootswatch themes) to alter the code
highlighting style. Previously all of the themes hosted their own
highlighting styles, but now that we are using the CDN, it is easier to
use a setting, which downstream themes can override.
---
 docs/user-guide/styling-your-docs.md  | 30 ++++++++++++++++-----------
 mkdocs/tests/config/config_tests.py   |  2 ++
 mkdocs/tests/theme_tests.py           |  1 +
 mkdocs/themes/mkdocs/base.html        |  2 +-
 mkdocs/themes/mkdocs/mkdocs_theme.yml |  1 +
 5 files changed, 23 insertions(+), 13 deletions(-)

diff --git a/docs/user-guide/styling-your-docs.md b/docs/user-guide/styling-your-docs.md
index b485b5b1..95278042 100644
--- a/docs/user-guide/styling-your-docs.md
+++ b/docs/user-guide/styling-your-docs.md
@@ -36,6 +36,10 @@ supports the following options:
 * __`highlightjs`__: Enables highlighting of source code in code blocks using
   the [highlight.js] JavaScript library. Default: `True`.
 
+* __`hljs_style`__: The highlight.js library provides 79 different [styles]
+  (color variations) for highlighting source code in code blocks. Set this to
+  the name of the desired style. Default: `github`.
+
 * __`hljs_languages`__: By default, highlight.js only supports 23 common
   languages. List additional languages here to include support for them.
 
@@ -69,12 +73,18 @@ supports the following options:
 
     * __`search`__: Display the search modal. Default: `83` (s)
 
+[styles]: https://highlightjs.org/static/demo/
+
 ### readthedocs
 
 A clone of the default theme used by the [Read the Docs] service, which offers
 the same restricted feature-set as its parent theme. Like its parent theme, only
-two levels of navigation are supported. In addition to the default [theme
-configuration options], the `readthedocs` theme supports the following options:
+two levels of navigation are supported.
+
+![ReadTheDocs](../img/readthedocs.png)
+
+In addition to the default [theme configuration options], the `readthedocs`
+theme supports the following options:
 
 * __`highlightjs`__: Enables highlighting of source code in code blocks using
   the [highlight.js] JavaScript library. Default: `True`.
@@ -82,16 +92,12 @@ configuration options], the `readthedocs` theme supports the following options:
 * __`hljs_languages`__: By default, highlight.js only supports 23 common
   languages. List additional languages here to include support for them.
 
-```yaml
-theme:
-    name: readthedocs
-    highlightjs: true
-    hljs_languages:
-        - yaml
-        - rust
-```
-
-![ReadTheDocs](../img/readthedocs.png)
+        theme:
+            name: readthedocs
+            highlightjs: true
+            hljs_languages:
+                - yaml
+                - rust
 
 ### Third Party Themes
 
diff --git a/mkdocs/tests/config/config_tests.py b/mkdocs/tests/config/config_tests.py
index 8f5fe08d..a096ab4d 100644
--- a/mkdocs/tests/config/config_tests.py
+++ b/mkdocs/tests/config/config_tests.py
@@ -130,6 +130,7 @@ class ConfigTests(unittest.TestCase):
                         'include_search_page': False,
                         'search_index_only': False,
                         'highlightjs': True,
+                        'hljs_style': 'github',
                         'hljs_languages': [],
                         'shortcuts': {'help': 191, 'next': 78, 'previous': 80, 'search': 83}
                     }
@@ -173,6 +174,7 @@ class ConfigTests(unittest.TestCase):
                         'include_search_page': False,
                         'search_index_only': False,
                         'highlightjs': True,
+                        'hljs_style': 'github',
                         'hljs_languages': [],
                         'shortcuts': {'help': 191, 'next': 78, 'previous': 80, 'search': 83}
                     }
diff --git a/mkdocs/tests/theme_tests.py b/mkdocs/tests/theme_tests.py
index 39e32a07..fb9c1381 100644
--- a/mkdocs/tests/theme_tests.py
+++ b/mkdocs/tests/theme_tests.py
@@ -32,6 +32,7 @@ class ThemeTests(unittest.TestCase):
             'include_search_page': False,
             'search_index_only': False,
             'highlightjs': True,
+            'hljs_style': 'github',
             'hljs_languages': [],
             'shortcuts': {'help': 191, 'next': 78, 'previous': 80, 'search': 83}
         })
diff --git a/mkdocs/themes/mkdocs/base.html b/mkdocs/themes/mkdocs/base.html
index 331184e6..b47fa119 100644
--- a/mkdocs/themes/mkdocs/base.html
+++ b/mkdocs/themes/mkdocs/base.html
@@ -21,7 +21,7 @@
         <link href="{{ 'css/font-awesome.min.css'|url }}" rel="stylesheet">
         <link href="{{ 'css/base.css'|url }}" rel="stylesheet">
         {%- if config.theme.highlightjs %}
-        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/github.min.css">
+        <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/{{ config.theme.hljs_style }}.min.css">
         {%- endif %}
         {%- for path in config['extra_css'] %}
         <link href="{{ path|url }}" rel="stylesheet">
diff --git a/mkdocs/themes/mkdocs/mkdocs_theme.yml b/mkdocs/themes/mkdocs/mkdocs_theme.yml
index d6109c23..33de9059 100644
--- a/mkdocs/themes/mkdocs/mkdocs_theme.yml
+++ b/mkdocs/themes/mkdocs/mkdocs_theme.yml
@@ -8,6 +8,7 @@ search_index_only: false
 
 highlightjs: true
 hljs_languages: []
+hljs_style: github
 
 shortcuts:
     help: 191    # ?