Added support for code block titles

.stylelintrc

@@ -98,6 +98,14 @@
       "vh",
       "vw"
     ],
+    "value-keyword-case": [
+      "lower",
+      {
+        "ignoreProperties": [
+          "/^--/"
+        ]
+      }
+    ],
     "value-list-comma-newline-after": null,
     "value-no-vendor-prefix": [
       true,

docs/reference/code-blocks.md

@@ -25,6 +25,10 @@ markdown_extensions:
   - pymdownx.snippets
 ```
 
+The following sections discuss how to use different syntax highlighting features
+with [Pygments], the recommended highlighter, so they don't apply when using a
+JavaScript syntax highlighter.
+
 See additional configuration options:
 
 - [Highlight]
@@ -79,12 +83,6 @@ theme:
 
 ## Usage
 
-This section discusses how to use different syntax highlighting features with
-[Pygments] – the default highlighter – so they don't apply when using
-a JavaScript syntax highlighter.
-
-### Specifying the language
-
 Code blocks must be enclosed with two separate lines containing three backticks.
 To add syntax highlighting to those blocks, add the language shortcode directly
 after the opening block. See the [list of available lexers] to find the
@@ -106,6 +104,39 @@ import tensorflow as tf
 
   [list of available lexers]: https://pygments.org/docs/lexers/
 
+### Adding a title
+
+[:octicons-tag-24: 7.3.6][Title support] ·
+:octicons-beaker-24: Experimental
+
+In order to provide additional context, a custom title can be added to a code
+block by using the `title="<custom title>"` option directly after the shortcode,
+e.g. to display the name of a file:
+
+_Example_:
+
+```` markdown
+``` py title="bubble_sort.py"
+def bubble_sort(items):
+    for i in range(len(items)):
+        for j in range(len(items) - 1 - i):
+            if items[j] > items[j + 1]:
+                items[j], items[j + 1] = items[j + 1], items[j]
+```
+````
+
+_Result_:
+
+``` py title="bubble_sort.py"
+def bubble_sort(items):
+    for i in range(len(items)):
+        for j in range(len(items) - 1 - i):
+            if items[j] > items[j + 1]:
+                items[j], items[j + 1] = items[j + 1], items[j]
+```
+
+  [Title support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.6
+
 ### Adding annotations
 
 Code annotations can be placed anywhere in a code block where a comment for the
@@ -253,14 +284,14 @@ from within a code block:
 _Example_:
 
 ```` markdown
-```
+``` title=".browserslistrc"
 --8<--​ ".browserslistrc"
 ```
 ````
 
 _Result_:
 
-```
+``` title=".browserslistrc"
 last 4 years
 ```
 

docs/reference/data-tables.md

@@ -30,8 +30,6 @@ See additional configuration options:
 
 ## Usage
 
-### Using data tables
-
 Data tables can be used at any position in your project documentation and can
 contain arbitrary Markdown, including inline code blocks, as well as [icons and
 emojis].

docs/setup/extensions/python-markdown-extensions.md

@@ -342,8 +342,8 @@ The following configuration options are supported:
         ```
 
         As an example, [Highlight.js], a JavaScript syntax highlighter, can be 
-        integrated with some [additional JavaScript] and [CSS][additional CSS]
-        in `mkdocs.yml`:
+        integrated with some [additional JavaScript] and [additional CSS] in
+        `mkdocs.yml`:
 
         === ":octicons-file-code-16: docs/javascripts/highlight.js"
 
@@ -363,7 +363,24 @@ The following configuration options are supported:
               - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.7.2/styles/default.min.css
             ```
 
-        Note that [Highlight.js] has no affiliation with the Highlight extension.
+        Note that [Highlight.js] has no affiliation with the
+        [Highlight][pymdownx.highlight] extension.
+
+    All following configuration options are only compatible with build-time
+    syntax highlighting using [Pygments], so they don't apply if `use_pygments`
+    is set to `false`.
+
+`auto_title`{ #highlight-auto-title }
+
+:   :octicons-milestone-24: Default: `false` – This option will automatically
+    add a [title] to all code blocks that shows the name of the language being
+    used, e.g. `Python` is printed for a `py` block:
+
+    ``` yaml
+    markdown_extensions:
+      - pymdownx.highlight:
+          auto_title: true
+    ```
 
 `linenums`{ #highlight-linenums }
 
@@ -403,7 +420,8 @@ them at your own risk.
 
 See reference for usage:
 
-- [Specifying the language]
+- [Using code blocks]
+- [Adding a title]
 - [Adding line numbers]
 - [Highlighting specific lines]
 - [Custom syntax theme]
@@ -416,8 +434,10 @@ See reference for usage:
   [Pygments]: https://pygments.org
   [additional CSS]: ../../customization.md#additional-css
   [Highlight.js]: https://highlightjs.org/
+  [title]: ../../reference/code-blocks.md#adding-a-title
   [Adding line numbers]: ../../reference/code-blocks.md#adding-line-numbers
-  [Specifying the language]: ../../reference/code-blocks.md#specifying-the-language
+  [Using code blocks]: ../../reference/code-blocks.md#usage
+  [Adding a title]: ../../reference/code-blocks.md#adding-a-title
   [Highlighting specific lines]: ../../reference/code-blocks.md#highlighting-specific-lines
   [Custom syntax theme]: ../../reference/code-blocks.md#custom-syntax-theme
 

docs/setup/extensions/python-markdown.md

@@ -340,7 +340,7 @@ No configuration options are available. See reference for usage:
 
   [Tables]: https://python-markdown.github.io/extensions/tables/
   [Tables support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
-  [Using data tables]: ../../reference/data-tables.md#using-data-tables
+  [Using data tables]: ../../reference/data-tables.md#usage
   [Column alignment]: ../../reference/data-tables.md#column-alignment
 
 ## Superseded extensions

material/base.html

@@ -39,7 +39,7 @@
       {% endif %}
     {% endblock %}
     {% block styles %}
-      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.cdeb8541.min.css' | url }}">
+      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.a57b2b03.min.css' | url }}">
       {% if config.theme.palette %}
         {% set palette = config.theme.palette %}
         <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.3f5d1f46.min.css' | url }}">

requirements.txt

@@ -23,5 +23,5 @@ jinja2>=2.11.1
 markdown>=3.2
 mkdocs>=1.2.3
 mkdocs-material-extensions>=1.0
-pygments>=2.4
+pygments>=2.10
 pymdown-extensions>=9.0

src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss

@@ -150,6 +150,25 @@
     background-color: var(--md-code-hl-color);
   }
 
+  // Code block title
+  span.filename {
+    position: relative;
+    display: block;
+    margin-top: 1em;
+    padding: px2em(10.5px, 13.6px) px2em(16px, 13.6px);
+    font-weight: 700;
+    font-size: px2em(13.6px);
+    background-color: var(--md-code-bg-color);
+    border-bottom: px2rem(1px) solid var(--md-default-fg-color--lightest);
+    border-top-left-radius: px2rem(2px);
+    border-top-right-radius: px2rem(2px);
+
+    // Adjust spacing for code block
+    + pre {
+      margin-top: 0;
+    }
+  }
+
   // Code block line numbers (inline)
   [data-linenos]::before {
     position: sticky;
@@ -195,6 +214,13 @@
     margin: 0;
   }
 
+  // Code block title container
+  th.filename {
+    flex-grow: 1;
+    padding: 0;
+    text-align: left;
+  }
+
   // Code block line numbers - disable user selection, so code can be easily
   // copied without accidentally also copying the line numbers
   .linenos {