📚 Fix sizing classes, grid rows, tab links, MyST prereqs

docs/css_classes.md

@@ -93,13 +93,13 @@ For more information, see [this guide to flexbox](https://css-tricks.com/snippet
 
 ## Sizing
 
-Size objects width/height by percentage:
+Size objects (`w`)idth/(`h`)eight by percentage:
 
-- `sd-width-25`, `sd-height-25`
-- `sd-width-50`, `sd-height-50`
-- `sd-width-75`, `sd-height-75`
-- `sd-width-100`, `sd-height-100`
-- `sd-width-auto`, `sd-height-auto`
+- `sd-w-25`, `sd-h-25`
+- `sd-w-50`, `sd-h-50`
+- `sd-w-75`, `sd-h-75`
+- `sd-w-100`, `sd-h-100`
+- `sd-w-auto`, `sd-h-auto`
 
 ## Spacing
 

docs/get_started.md

@@ -24,6 +24,14 @@ extensions = ["myst_parser", "sphinx_design"]
 myst_enable_extensions = ["colon_fence"]
 ```
 
+:::{note}
+The MyST Markdown examples in this documentation assume that certain optional [MyST syntax extensions](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html) have been enabled, *via* the `myst_enable_extensions` configuration above:
+
+- `colon_fence`: used by all examples, to write directives delimited by `:::` fences
+- `html_image`: only for examples using raw HTML `<img>` tags, such as the avatar images in [CSS Classes](./css_classes.md)
+- `attrs_inline`: only for examples adding attributes to inline elements, such as the links to synchronised [Tabs](./tabs.md)
+:::
+
 ## Configuration
 
 To hide the title header of a page, add to the top of the page:

docs/grids.md

@@ -10,6 +10,10 @@ A `grid` directive can be set with the number of default columns (1 to 12);
 either a single number for all screen sizes, or four numbers for extra-small (<576px), small (768px), medium (992px) and large screens (>1200px),
 then child `grid-item` directives should be set for each item.
 
+Note, a single number **fixes** the number of columns for all screen sizes,
+whereas four numbers allow the layout to adapt responsively to the screen size,
+as in the example below.
+
 Try re-sizing the screen to see the number of columns change:
 
 ::::{grid} 1 2 3 4
@@ -65,6 +69,54 @@ short text content
 :::
 ::::
 
+## Multiple rows
+
+There is no need to add a directive per row;
+when the number of items exceeds the number of columns,
+the additional items simply wrap onto new rows, as required:
+
+::::{grid} 3
+:outline:
+
+:::{grid-item}
+A
+:::
+:::{grid-item}
+B
+:::
+:::{grid-item}
+C
+:::
+:::{grid-item}
+D
+:::
+::::
+
+However, to deliberately separate items into distinct rows,
+use a separate `grid` directive for each row:
+
+::::{grid} 3
+:outline:
+
+:::{grid-item}
+A
+:::
+:::{grid-item}
+B
+:::
+::::
+
+::::{grid} 3
+:outline:
+
+:::{grid-item}
+C
+:::
+:::{grid-item}
+D
+:::
+::::
+
 ## Placing a card in a grid
 
 The `grid-item-card` directive is a short-hand for placing a card content container inside a grid item (see [Cards](./cards.md)). Most of the `card` directive's options can be used also here:
@@ -134,7 +186,9 @@ B
 You can override the number of columns a single item takes up by using the `columns` option of the `grid-item` directive.
 Given the total columns are 12, this means 12 would indicate a single item takes up the entire grid row, or 6 half.
 Alternatively, use `auto` to automatically decide how many columns to use based on the item content.
-Like for grid columns, you can either provide a single number or four for small, medium and large and extra-large screens.
+Like for grid columns, you can either provide a single number or four for small, medium and large and extra-large screens,
+and likewise, a single number fixes the item's width for all screen sizes,
+overriding any responsive behaviour set by the parent `grid`.
 
 ::::{grid} 2
 :::{grid-item-card}

docs/tabs.md

@@ -97,6 +97,33 @@ Content 2
 ````
 `````
 
+### Linking to synchronised tabs
+
+To author a link that pre-selects a tab, append the query string (and optionally a page anchor) to the URL of the **built** HTML page.
+Sphinx referencing roles, such as `ref` and `doc`, cannot output URLs containing query strings,
+so instead write the URL directly:
+
+- In MyST Markdown, add an `external` class to the link (using the [`attrs_inline` extension](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html)), so that the URL is output as-is, rather than being resolved as a cross-reference.
+- In reStructuredText, use a standard (external) hyperlink.
+
+````{tab-set-code}
+```{code-block} markdown
+[Open with key2 selected](tabs.html?category=key2#synchronised-tabs){.external}
+```
+```{code-block} rst
+`Open with key2 selected <tabs.html?category=key2#synchronised-tabs>`_
+```
+````
+
+For example: [open the tabs above with `key2` selected](tabs.html?category=key2#synchronised-tabs){.external}
+
+:::{warning}
+Such URLs are relative to the location of the current page in the built HTML output, not to the source files
+(for example, a page in a sub-folder would require `../tabs.html?...`).
+They are not checked by Sphinx, so they will break silently if the target page is moved,
+and they do not apply to other output formats.
+:::
+
 ## Tabbed code examples
 
 The `tab-set-code` directive provides a shorthand for synced code examples.