From 39180ba24195b09e0904960ca7c376b1c8578592 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 12 Jul 2026 13:03:54 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9A=20DOCS:=20Fix=20sizing=20classes,?= =?UTF-8?q?=20grid=20rows,=20tab=20links,=20MyST=20prereqs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Correct the sizing CSS class names to the generated `sd-w-{25,50,75,100,auto}` / `sd-h-{25,50,75,100,auto}` (per `style/_sizing.scss`) (#172) - Note the MyST syntax extensions (`colon_fence`, `html_image`, `attrs_inline`) that the documentation examples rely on (#122) - Add a "Multiple rows" section to the grid docs, and clarify that a single-value column count is fixed across all screen sizes, for both the `grid` argument and the item-level `columns` option (#184, #182) - Document how to author links to synchronised tabs with query strings, from both MyST Markdown and reStructuredText (#247) --- docs/css_classes.md | 12 +++++----- docs/get_started.md | 8 +++++++ docs/grids.md | 56 ++++++++++++++++++++++++++++++++++++++++++++- docs/tabs.md | 27 ++++++++++++++++++++++ 4 files changed, 96 insertions(+), 7 deletions(-) diff --git a/docs/css_classes.md b/docs/css_classes.md index b87e1d18..f6f1b32f 100644 --- a/docs/css_classes.md +++ b/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 diff --git a/docs/get_started.md b/docs/get_started.md index 48ecfd50..16f0f83d 100644 --- a/docs/get_started.md +++ b/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 `` 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: diff --git a/docs/grids.md b/docs/grids.md index 69b987d7..5de87e1e 100644 --- a/docs/grids.md +++ b/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} diff --git a/docs/tabs.md b/docs/tabs.md index 25114d15..3f19b886 100644 --- a/docs/tabs.md +++ b/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 `_ +``` +```` + +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.