Added documentation for data tables

docs/reference/data-tables.md

@@ -0,0 +1,171 @@
+---
+template: overrides/main.html
+---
+
+# Data tables
+
+Material for MkDocs defines default styles for data tables – an excellent way
+of rendering tabular data in project documentation. Furthermore, customizations
+like [sortable tables][1] can be achieved with a third-party library and some
+[additional JavaScript][2].
+
+  [1]: #sortable-tables
+  [2]: ../customization.md#additional-javascript 
+
+## Configuration
+
+None.
+
+## 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][3].
+
+_Example_:
+
+``` markdown
+| Method      | Description                          |
+| ----------- | ------------------------------------ |
+| `GET`       | :material-check:     Fetch resource  |
+| `PUT`       | :material-check-all: Update resource |
+| `DELETE`    | :material-close:     Delete resource |
+```
+
+_Result_:
+
+| Method      | Description                          |
+| ----------- | ------------------------------------ |
+| `GET`       | :material-check:     Fetch resource  |
+| `PUT`       | :material-check-all: Update resource |
+| `DELETE`    | :material-close:     Delete resource |
+
+  [3]: icons-emojis.md
+
+### Column alignment
+
+If you want to align a specific column to the `left`, `center` or `right`, you
+can use the [regular Markdown syntax][4] placing `:` characters at the beginning
+and/or end of the divider.
+
+=== "Left"
+
+    _Example_:
+
+    ``` markdown hl_lines="2"
+    | Method      | Description                          |
+    | :---------- | :----------------------------------- |
+    | `GET`       | :material-check:     Fetch resource  |
+    | `PUT`       | :material-check-all: Update resource |
+    | `DELETE`    | :material-close:     Delete resource |
+    ```
+
+    _Result_:
+
+    | Method      | Description                          |
+    | :---------- | :----------------------------------- |
+    | `GET`       | :material-check:     Fetch resource  |
+    | `PUT`       | :material-check-all: Update resource |
+    | `DELETE`    | :material-close:     Delete resource |
+
+=== "Center"
+
+    _Example_:
+
+    ``` markdown hl_lines="2"
+    | Method      | Description                          |
+    | :---------: | :----------------------------------: |
+    | `GET`       | :material-check:     Fetch resource  |
+    | `PUT`       | :material-check-all: Update resource |
+    | `DELETE`    | :material-close:     Delete resource |
+    ```
+
+    _Result_:
+
+    | Method      | Description                          |
+    | :---------: | :----------------------------------: |
+    | `GET`       | :material-check:     Fetch resource  |
+    | `PUT`       | :material-check-all: Update resource |
+    | `DELETE`    | :material-close:     Delete resource |
+
+=== "Right"
+
+    _Example_:
+
+    ``` markdown hl_lines="2"
+    | Method      | Description                          |
+    | ----------: | -----------------------------------: |
+    | `GET`       | :material-check:     Fetch resource  |
+    | `PUT`       | :material-check-all: Update resource |
+    | `DELETE`    | :material-close:     Delete resource |
+    ```
+
+    _Result_:
+
+    | Method      | Description                          |
+    | ----------: | -----------------------------------: |
+    | `GET`       | :material-check:     Fetch resource  |
+    | `PUT`       | :material-check-all: Update resource |
+    | `DELETE`    | :material-close:     Delete resource |
+
+  [4]: https://www.markdownguide.org/extended-syntax/#tables
+
+## Customization
+
+### Sortable tables
+
+If you want to make data tables sortable, you can add [tablesort][5] via
+[additional JavaScript][2], which is natively integrated with Material for
+MkDocs and will also work with [instant loading][6]:
+
+=== "docs/javascripts/tables.js"
+
+    ``` js
+    app.location$.subscribe(function() {
+      var tables = document.querySelectorAll("article table")
+      tables.forEach(function(table) {
+        new Tablesort(table)
+      })
+    })
+    ```
+
+=== "mkdocs.yml"
+
+    ``` yaml
+    extra_javascript:
+      - https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js
+      - javascripts/tables.js
+    ```
+
+_Note that [tablesort][5] provides alternative comparison implementations like
+numbers, dates, filesizes and month names. See the official documentation for
+more information._
+
+_Example_:
+
+``` markdown
+| Method      | Description                          |
+| ----------- | ------------------------------------ |
+| `GET`       | :material-check:     Fetch resource  |
+| `PUT`       | :material-check-all: Update resource |
+| `DELETE`    | :material-close:     Delete resource |
+```
+
+_Result_:
+
+| Method      | Description                          |
+| ----------- | ------------------------------------ |
+| `GET`       | :material-check:     Fetch resource  |
+| `PUT`       | :material-check-all: Update resource |
+| `DELETE`    | :material-close:     Delete resource |
+
+<script src="https://cdnjs.cloudflare.com/ajax/libs/tablesort/5.2.1/tablesort.min.js"></script>
+<script>
+  var tables = document.querySelectorAll("article table")
+  new Tablesort(tables.item(tables.length - 1));
+</script>
+
+  [5]: http://tristen.ca/tablesort/demo/
+  [6]: ../setup/setting-up-navigation.md#instant-loading

docs/reference/mathjax.md

@@ -34,7 +34,7 @@ Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and
 the JavaScript runtime need to be included, which can be done with [additional 
 JavaScript][8]:
 
-=== "docs/javascript/config.js"
+=== "docs/javascripts/config.js"
 
     ``` js
     window.MathJax = {

material/assets/manifest.json

@@ -5,8 +5,8 @@
   "assets/javascripts/vendor.js.map": "assets/javascripts/vendor.c3dc8c49.min.js.map",
   "assets/javascripts/worker/search.js": "assets/javascripts/worker/search.8e2cddea.min.js",
   "assets/javascripts/worker/search.js.map": "assets/javascripts/worker/search.8e2cddea.min.js.map",
-  "assets/stylesheets/main.css": "assets/stylesheets/main.e584d62f.min.css",
-  "assets/stylesheets/main.css.map": "assets/stylesheets/main.e584d62f.min.css.map",
+  "assets/stylesheets/main.css": "assets/stylesheets/main.6fb40bf7.min.css",
+  "assets/stylesheets/main.css.map": "assets/stylesheets/main.6fb40bf7.min.css.map",
   "assets/stylesheets/overrides.css": "assets/stylesheets/overrides.011ebae6.min.css",
   "assets/stylesheets/overrides.css.map": "assets/stylesheets/overrides.011ebae6.min.css.map",
   "assets/stylesheets/palette.css": "assets/stylesheets/palette.cef4c379.min.css",

material/base.html

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

mkdocs.yml

@@ -168,6 +168,7 @@ nav:
     - Buttons: reference/buttons.md
     - Code blocks: reference/code-blocks.md
     - Content tabs: reference/content-tabs.md
+    - Data tables: reference/data-tables.md
     - Footnotes: reference/footnotes.md
     - Formatting: reference/formatting.md
     - Icons + Emojis: reference/icons-emojis.md

src/assets/stylesheets/main/_typeset.scss

@@ -51,6 +51,14 @@ kbd {
 // Rules: typesetted content
 // ----------------------------------------------------------------------------
 
+// Icon definitions
+:root {
+  --md-typeset-table--ascending: svg-load("@mdi/svg/svg/arrow-down.svg");
+  --md-typeset-table--descending: svg-load("@mdi/svg/svg/arrow-up.svg");
+}
+
+// ----------------------------------------------------------------------------
+
 // Content that is typeset - if possible, all margins, paddings and font sizes
 // should be set in ems, so nested blocks (e.g. admonitions) render correctly,
 // except headlines that should only appear on the top level and need to have
@@ -437,7 +445,7 @@ kbd {
     display: inline-block;
     max-width: 100%;
     overflow: auto;
-    font-size: px2em(12.8px);
+    font-size: px2rem(12.8px);
     background: var(--md-default-bg-color);
     border-radius: px2rem(2px);
     box-shadow:
@@ -521,6 +529,34 @@ kbd {
     }
   }
 
+  // Sortable tables
+  table th[role="columnheader"] {
+    cursor: pointer;
+
+    // Icons
+    &::after {
+      display: inline-block;
+      width: 1.2em;
+      height: 1.2em;
+      margin-left: 0.5em;
+      vertical-align: sub;
+      mask-repeat: no-repeat;
+      content: " ";
+    }
+
+    // Sort ascending
+    &[aria-sort="ascending"]::after {
+      background-color: currentColor;
+      mask-image: var(--md-typeset-table--ascending);
+    }
+
+    // Sort descending
+    &[aria-sort="descending"]::after {
+      background-color: currentColor;
+      mask-image: var(--md-typeset-table--descending);
+    }
+  }
+
   // Wrapper for scrolling on overflow
   &__scrollwrap {
     margin: 1em px2rem(-16px);