Added first part of syntax highlighting guide

docs/customization.md

@@ -72,7 +72,7 @@ parts of a theme without forking and changing the main theme.
 
 ### Setup and theme structure
 
-Reference the Material theme as usual in `mkdocs.yml`, and create a new folder
+Reference the original theme as usual in `mkdocs.yml`, and create a new folder
 for `overrides` which you reference using `custom_dir`:
 
 ``` yaml

docs/guides/changing-colors.md

@@ -280,4 +280,3 @@ colors or neutral colors:
   [7]: ../customization.md#additional-stylesheets
   [8]: ../extensions/codehilite.md
   [9]: ../extensions/admonition.md
-

docs/guides/changing-the-fonts.md

@@ -94,6 +94,6 @@ The font can then be configured to be used as the regular or proportional font:
     ```
 
   [5]: ../data-privacy.md
-  [6]: ../customization.md#setup-and-theme-structure
+  [6]: ../customization.md#extending-the-theme
   [7]: ../customization.md#overriding-blocks
   [8]: ../customization.md#additional-stylesheets

docs/guides/changing-the-language.md

@@ -172,4 +172,4 @@ theme:
   language: en-custom
 ```
 
-  [6]: ../customization.md#setup-and-theme-structure
+  [6]: ../customization.md#extending-the-theme

docs/guides/navigation.md

@@ -125,7 +125,7 @@ customize its appearance:
 :   This option allows for customization of the slug function. For some
     languages, the standard slug function may not produce good and readable
     identifiers. Consider using another slug function like for example those
-    from [PyMdown Extensions][8]:
+    from [Python Markdown Extensions][8]:
 
     === "Unicode"
 
@@ -173,3 +173,13 @@ this extension, so they may yield weird results. Use them at your own risk._
   [6]: https://python-markdown.github.io/extensions/toc/
   [7]: https://python-markdown.github.io/extensions/toc/#usage
   [8]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+
+## Customization
+
+All navigational elements are defined as partials and can be overridden through
+[theme extension][9] by [overriding partials][10] or [blocks][11], i.e.
+`site_nav` which contains both sidebars, `tabs` and `footer`.
+
+  [9]: ../customization.md#extending-the-theme
+  [10]: ../customization.md#overriding-partials
+  [11]: ../customization.md#overriding-blocks

docs/guides/syntax-highlighting.md

@@ -0,0 +1,72 @@
+---
+template: overrides/main.html
+---
+
+# Syntax highlighting
+
+Code blocks and examples are an essential part of technical project
+documentation. Material for MkDocs provides different ways to set up syntax
+highlighting for code blocks, either during build time using [Pygments][1] or
+during runtime using a JavaScript syntax highlighter.
+
+  [1]: https://pygments.org
+
+## Configuration
+
+### Highlight
+
+[:octicons-file-code-24: Source][2] · [:octicons-workflow-24: Extension][3]
+
+The [highlight][3] extension, which is part of [Python Markdown Extensions][4],
+integrates with Material for MkDocs and provides several options for
+configuring syntax highlighting of code blocks:
+
+`use_pygments`
+
+:   This option allows to control whether highlighting should be carried out
+    during build time by [Pygments][1] (default, recommended) or runtime with
+    a JavaScript highlighter. Remember to add the necessary 
+    [additional stylesheets][5] and [JavaScript][6] if you want to use the
+    latter:
+
+    === "Pygments"
+
+        ``` yaml
+        markdown_extensions:
+          - pymdownx.highlight:
+              use_pygments: true
+        ```
+
+    === "JavaScript"
+
+        ``` yaml
+        markdown_extensions:
+          - pymdownx.highlight:
+              use_pygments: false
+        ```
+
+    ??? example "Syntax highlighting with [Highlight.js][7]"
+
+        Highlight.js can be integrated by including the respective stylesheet
+        and JavaScript from a [CDN][8] in `mkdocs.yml`:
+
+        ``` yaml
+        extra_javascript:
+          - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/highlight.min.js
+        extra_css:
+          - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/styles/default.min.css
+        ```
+
+        Additionally, the following function must be called:
+
+        ``` js
+        hljs.initHighlighting()
+        ```
+
+  [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/extensions/pymdown/_highlight.scss
+  [3]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
+  [4]: https://facelessuser.github.io/pymdown-extensions/
+  [5]: ../customization.md#additional-stylesheets
+  [6]: ../customization.md#additional-javascript
+  [7]: https://highlightjs.org/
+  [8]: https://cdnjs.com/libraries/highlight.js/

material/assets/manifest.json

@@ -5,8 +5,8 @@
   "assets/javascripts/vendor.js.map": "assets/javascripts/vendor.568ba93b.min.js.map",
   "assets/javascripts/worker/search.js": "assets/javascripts/worker/search.a68abb33.min.js",
   "assets/javascripts/worker/search.js.map": "assets/javascripts/worker/search.a68abb33.min.js.map",
-  "assets/stylesheets/main.css": "assets/stylesheets/main.660197c7.min.css",
-  "assets/stylesheets/main.css.map": "assets/stylesheets/main.660197c7.min.css.map",
+  "assets/stylesheets/main.css": "assets/stylesheets/main.04aed59c.min.css",
+  "assets/stylesheets/main.css.map": "assets/stylesheets/main.04aed59c.min.css.map",
   "assets/stylesheets/palette.css": "assets/stylesheets/palette.e185632b.min.css",
   "assets/stylesheets/palette.css.map": "assets/stylesheets/palette.e185632b.min.css.map"
 }

material/base.html

@@ -41,7 +41,7 @@
       {% endif %}
     {% endblock %}
     {% block styles %}
-      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.660197c7.min.css' | url }}">
+      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.04aed59c.min.css' | url }}">
       {% if palette.scheme or palette.primary or palette.accent %}
         <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.e185632b.min.css' | url }}">
       {% endif %}

mkdocs.yml

@@ -90,8 +90,6 @@ extra:
 markdown_extensions:
   - markdown.extensions.admonition
   - markdown.extensions.attr_list
-  - markdown.extensions.codehilite:
-      guess_lang: false
   - markdown.extensions.def_list
   - markdown.extensions.footnotes
   - markdown.extensions.meta
@@ -106,7 +104,8 @@ markdown_extensions:
   - pymdownx.emoji:
       emoji_index: !!python/name:materialx.emoji.twemoji
       emoji_generator: !!python/name:materialx.emoji.to_svg
-  # - pymdownx.highlight:
+  - pymdownx.highlight:
+      use_pygments: true
   #     linenums_style: pymdownx-inline
   - pymdownx.inlinehilite
   - pymdownx.keys
@@ -140,12 +139,13 @@ nav:
     - Changing the language: guides/changing-the-language.md
     - Navigation: guides/navigation.md
     - Syntax highlighting: guides/syntax-highlighting.md
-    - Adding a landing page: guides/adding-a-landing-page.md
+    - Adding a git repository: guides/adding-a-git-repository.md
     - Adding an announcement bar: guides/adding-an-announcement-bar.md
     - Adding icons and emojis: guides/adding-icons-and-emojis.md
     - Adding footer links: guides/adding-footer-links.md
     - Adding site analytics: guides/adding-site-analytics.md
     - Adding a comment system: guides/adding-a-comment-system.md
+    - Adding a landing page: guides/adding-a-landing-page.md
   - Extensions:
     - Admonition: extensions/admonition.md
     - CodeHilite: extensions/codehilite.md