example
+!!! Info "Information" + The examples in this document use `` to provide a grey background that distinguishes examples from normal text. However, we do not use this convention in our actual documentation.
```
-
## Code
Inline code and code blocks render in APL font unless the class "language-other" is used.
@@ -362,15 +384,8 @@ The average of a vector (example
+example +{ .example} + This is an example ```
-
>
+example
+example +{ .example} + This is an example -+⌿÷≢) is the sum
>
#### APL Code blocks
-Code blocks use `Example: Using HTML
- -``` - 3+⍳10
-4 5 6 7 8 9 10 11 12 13
-[your code here]` or triple backticks with "other" (lowercase).
-
-Example: Using HTML
- -``` ->>> print("hello") # Code block example
-helloExample: Using backticks
`````` -```other +```python >>> print("hello") # Code block example hello ``` `````` -```other +```pythom >>> print("hello") # Code block example hello ``` @@ -465,39 +468,28 @@ When referring to keyboard shortcuts, such as those controlled by `⎕KL` on Mic Closing angle brackets must be escaped with a backslash (e.g. `Example
+Example +{ .example} ```Example
+example +{ .example} ``` Press the Enter key. ``` -
Press the Enter key.
-
>
-
-## Figures with Captions
-!!! Info "Information"
- There is currently no way to automatically number and cross-reference figures in Material for MkDocs.
-
-
-Example
``` -Use :material-apple-keyboard-command: + C to copy text +Use :material-apple-keyboard-command: + C to copy text ```
diff --git a/docs/tables.md b/docs/tables.md
new file mode 100644
index 0000000..cfeb4bb
--- /dev/null
+++ b/docs/tables.md
@@ -0,0 +1,75 @@
+# Tables
+
+!!! note "Tables are not standard Markdown"
+ Tables were not part of the original Markdown specification, but was popularised by the widely used [GitHub-Flavoured Markdown](https://github.github.com/gfm/) (GFM) dialect.
+
+GFM table syntax only allows for the most basic of tables. To remedy this, we use the [Tables-Extended](https://github.com/fumbles/tables_extended) Markdown extension to allow for more elaborate tables, and the [caption](https://github.com/tobiasah/mkdocs-caption#readme) plugin for captions, automatic numbering and references.
+
+In its most basic form, a GFM table must have a header row:
+
+```other
+| heading 1 | heading 2 |
+| --------- | --------- |
+| content 1 | content 2 |
+| content 3 | content 4 |
+```
+
+which renders as:
+
+| heading 1 | heading 2 |
+| --------- | --------- |
+| content 1 | content 2 |
+| content 3 | content 4 |
+
+With the extension, we can make headerless tables in a natural way:
+
+```other
+| --------- | --------- |
+| content 1 | content 2 |
+| content 3 | content 4 |
+```
+
+which renders as:
+
+| --------- | --------- |
+| content 1 | content 2 |
+| content 3 | content 4 |
+
+You can also create row-, and col-spans with easily accessible syntax. See the [Tables-Extended](https://github.com/fumbles/tables_extended) documentation for details.
+
+!!! note "Tables are for data, not layout"
+ Tables should be used for data, not document structure or layout. Unless you have a good reason not to, do name your columns. Complex tables are hard to read on a screen. If you find yourself reaching for more complex table layouts, consider if there are better ways to present the information.
+
+## Captions and References
+
+To caption a table, add a line beginning with "Table: " just before the table, and assign an id using an attribute list:
+
+
+Table: Cells with content { #MyTable }
+
+| heading 1 | heading 2 |
+| --------- | --------- |
+| content 1 | content 2 |
+| content 3 | content 4 |
+
+
+which should render as:
+
+Table: Cells with content { #MyTable }
+
+| heading 1 | heading 2 |
+| --------- | --------- |
+| content 1 | content 2 |
+| content 3 | content 4 |
+
+You, the author, are responsible for choosing a unique table id (the `#MyTable` in this case) which is unique and appropriate for the table.
+
+To reference a table based on its id, insert a Markdown link to the id, with an empty anchor:
+
++As shown in [](#MyTable), yadda yadda. ++ +where the anchor text should be filled in by the extension: + +As shown in [](#MyTable), yadda yadda. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index e099ba2..96cb33d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,6 +5,13 @@ theme: favicon: 'img/favicon-32.png' language: en logo: 'img/dyalog-white.svg' +plugins: + - caption: + table: + enable: true + start_index: 1 + increment_index: 1 + position: bottom markdown_extensions: - admonition - pymdownx.highlight: @@ -16,6 +23,9 @@ markdown_extensions: - pymdownx.emoji: emoji_index: !!python/name:materialx.emoji.twemoji emoji_generator: !!python/name:materialx.emoji.to_svg + - markdown_tables_extended + - toc: + title: On this page extra_css: - styles/custom-admonitions.css - styles/main.css @@ -23,4 +33,7 @@ nav: - Home: index.md - Rules for Writing Documentation: rules.md - Style Guide: style.md + - Images: images.md + - Tables: tables.md + - CSS: css.md - Process: process.md \ No newline at end of file