From 0c4885d7c36fa0cea439d4dc5331e902a9df1459 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Fri, 6 Mar 2026 16:03:50 -0300 Subject: [PATCH 1/4] DOC: Fix documentation about margin and sidebar directives --- docs/content/content-blocks.md | 58 +++++++++++++++++++++++++++++----- 1 file changed, 50 insertions(+), 8 deletions(-) diff --git a/docs/content/content-blocks.md b/docs/content/content-blocks.md index f331af41..f9c02df2 100644 --- a/docs/content/content-blocks.md +++ b/docs/content/content-blocks.md @@ -141,10 +141,17 @@ If you'd like in-line margin content with numbered references, see [](margin:sid Here's how you can use the `{margin}` directive: -````{example} -:no-container: -:reverse: +```{margin} **Here is my margin content** +It is pretty cool! +``` +:::{important} +The `{margin}` directive should not be nested under other elements such as topics or admonitions. +::: + +**Source:** + +```` ```{margin} **Here is my margin content** It is pretty cool! ``` @@ -217,6 +224,8 @@ We can reference the figure with {ref}`myfig4`. Or a numbered reference like Margin content can include all kinds of things, such as code blocks: +**Code blocks in the margin** + ````{margin} Code blocks in margins ```python print("here is some python") @@ -228,12 +237,34 @@ print("here is some python") print("here is some python") ``` ```` + +**Source:** ````` +````{margin} Code blocks in margins +```python +print("here is some python") +``` +```` -`````{example} Admonitions and images in the margin -:no-container: -:reverse: +````{margin} Code blocks in margins +```python +print("here is some python") +``` +```` +````` + +**Admonitions and images in the margin** + +````{margin} **Notes in margins** +```{note} +Wow, a note with an image in a margin! +![](../images/cool.jpg) +``` +```` + +**Source:** +````` ````{margin} **Notes in margins** ```{note} Wow, a note with an image in a margin! @@ -249,9 +280,16 @@ page to flow around them, rather than moving to the right margin. To add content sidebars, use this syntax: -`````{example} -:no-container: +````{sidebar} **My sidebar title** +```{note} +Here is my sidebar content, it is pretty cool! +``` +![](../images/cool.jpg) +```` + +**Source:** +````` ````{sidebar} **My sidebar title** ```{note} Here is my sidebar content, it is pretty cool! @@ -265,6 +303,10 @@ However, the sidebar text will still be in line with your content. There are certain kinds of elements, such as "note" blocks and code cells, that may clash with your sidebar. If this happens, try using a `{margin}` instead. +:::{important} +The `{sidebar}` directive should not be nested under other elements such as topics or admonitions. +::: + ## Full-width content Full-width content extends into the right margin, making it stand out against From d3ff394432b7bbc106446a763b2f1b3db4e70dd4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Fri, 6 Mar 2026 16:08:55 -0300 Subject: [PATCH 2/4] DOC: Fix margin directive in setup docs --- docs/contributing/setup.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/contributing/setup.md b/docs/contributing/setup.md index 94db9b13..d1e7404e 100644 --- a/docs/contributing/setup.md +++ b/docs/contributing/setup.md @@ -39,17 +39,17 @@ Follow these steps: $ pre-commit install ``` - :::{margin} - You can also run pre-commit via `tox`: - ```console - $ tox -e py38-pre-commit -- --all - ``` - or manually run all `pre-commit` jobs for this repository: +:::{margin} +You can also run pre-commit via `tox`: +```console +$ tox -e py38-pre-commit -- --all +``` +or manually run all `pre-commit` jobs for this repository: - ```console - $ pre-commit run --all-files - ``` - ::: +```console +$ pre-commit run --all-files +``` +::: The rest of these instructions use `tox` to automate the installation and commands necessary to do many common things. From 7530ea53fd8b05cadd169ba4e97674636d5768c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Fri, 6 Mar 2026 18:09:56 -0300 Subject: [PATCH 3/4] DOC: Accept code review suggestions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Brigitta Sipőcz --- docs/content/content-blocks.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/content/content-blocks.md b/docs/content/content-blocks.md index f9c02df2..1ca3ef88 100644 --- a/docs/content/content-blocks.md +++ b/docs/content/content-blocks.md @@ -149,7 +149,7 @@ It is pretty cool! The `{margin}` directive should not be nested under other elements such as topics or admonitions. ::: -**Source:** +**Source** ```` ```{margin} **Here is my margin content** @@ -238,7 +238,7 @@ print("here is some python") ``` ```` -**Source:** +**Source** ````` ````{margin} Code blocks in margins ```python @@ -248,7 +248,7 @@ print("here is some python") ````{margin} Code blocks in margins ```python -print("here is some python") +print("here is some other python") ``` ```` ````` @@ -262,7 +262,7 @@ Wow, a note with an image in a margin! ``` ```` -**Source:** +**Source** ````` ````{margin} **Notes in margins** @@ -287,7 +287,7 @@ Here is my sidebar content, it is pretty cool! ![](../images/cool.jpg) ```` -**Source:** +**Source** ````` ````{sidebar} **My sidebar title** From 97c6ecc6701629b7bab0a31dceeeddd8f6351130 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Fri, 6 Mar 2026 18:23:44 -0300 Subject: [PATCH 4/4] DOC: Remove duplicated code block example --- docs/content/content-blocks.md | 13 +------------ 1 file changed, 1 insertion(+), 12 deletions(-) diff --git a/docs/content/content-blocks.md b/docs/content/content-blocks.md index 1ca3ef88..4ef45490 100644 --- a/docs/content/content-blocks.md +++ b/docs/content/content-blocks.md @@ -232,25 +232,14 @@ print("here is some python") ``` ```` -````{margin} Code blocks in margins -```python -print("here is some python") -``` -```` - **Source** + ````` ````{margin} Code blocks in margins ```python print("here is some python") ``` ```` - -````{margin} Code blocks in margins -```python -print("here is some other python") -``` -```` ````` **Admonitions and images in the margin**