directives

Author: jpsca

docs/assets/icons/scissors.svg

@@ -6,4 +6,30 @@ export function ready() {
       if (pop) { pop.hidePopover(); }
     });
   });
+
+  if (!window.scrollPositions) {
+    window.scrollPositions = {};
+  }
+  window.addEventListener("turbo:before-cache", preserveScroll)
+  window.addEventListener("turbo:before-render", restoreScroll)
+  window.addEventListener("turbo:render", restoreScroll)
+}
+
+function preserveScroll () {
+  document.querySelectorAll("[data-preserve-scroll]").forEach((element) => {
+    scrollPositions[element.id] = element.scrollTop;
+  })
+}
+
+function restoreScroll (event) {
+  document.querySelectorAll("[data-preserve-scroll]").forEach((element) => {
+    element.scrollTop = scrollPositions[element.id];
+  })
+
+  if (!event.detail.newBody) return
+  // event.detail.newBody is the body element to be swapped in.
+  // https://turbo.hotwired.dev/reference/events
+  event.detail.newBody.querySelectorAll("[data-preserve-scroll]").forEach((element) => {
+    element.scrollTop = scrollPositions[element.id];
+  })
 }

docs/assets/js/page.js

@@ -0,0 +1,22 @@
+---
+title: Divs
+icon: icons/blocks.svg
+---
+
+This is a generic wrapper with HTML classes to customize your documents.
+
+Instead of a title, the text after the name will be added as classes:
+
+```md
+::: div my-class another-class
+Any markdown content
+:::
+```
+
+will render as
+
+```html
+<div class="my-class another-class">
+<p>Any markdown content</p>
+</div>
+```

docs/content/markdown/admonitions.md docs/content/directives/admonitions.mddocs/content/markdown/admonitions.md renamed to docs/content/directives/admonitions.md

@@ -0,0 +1,20 @@
+---
+title: Figures
+icon: icons/image.svg
+---
+
+The Markdown syntax doesn't provide native support for image captions, but you can use a `::: figure` block:
+
+:::: div example
+
+```markdown
+::: figure | Image caption
+![Alt text](/assets/images/image.png)
+:::
+```
+
+::: figure | Image caption
+![Alt text](/assets/images/image.png)
+:::
+::::
+

docs/content/directives/divs.md

@@ -0,0 +1,29 @@
+---
+title: Directives
+---
+
+WriteADoc add to the  common markdwown syntax some popular extensions it calls "directives". A directive starts and end with at least three periods `:::` and a name:
+
+```markdown
+::: name | Some text
+:option1:=value1
+
+Markdown content
+:::
+```
+
+The `|` after the name is optional
+
+## Nested directives
+
+You can nest directives to add, for example, an admonition inside an div. To do so just use more ":" to the outer directive:
+
+```md
+:::: div wrapper
+
+::: note
+Hello
+:::
+
+::::
+```

docs/content/directives/figures.md

@@ -74,3 +74,13 @@ Tab 1 content
 Tab 2 should be selected by default.
 :::
 ```
+
+::: tab | Tab 1 title
+Tab 1 content
+:::
+
+::: tab | Tab 2 title
+:select: True
+
+Tab 2 should be selected by default.
+:::

docs/content/directives/index.md

@@ -66,7 +66,8 @@ When the markdown attribute is set to "block", the parser will force block behav
 
 The content of a block element is parsed into block-level content. In other words, the text is rendered as paragraphs, headers, lists, blockquotes, etc. Any inline syntax within those elements is processed as well.
 
-/// example | Forced "block" markdown parsing
+:::: div example
+**Example: Forced "block" markdown parsing**
 
 ```md
 <section markdown="block">
@@ -93,16 +94,14 @@ renders as:
 </section>
 ```
 
-///
-
-<!--  -->
+::::
 
-/// warning
+::: warning
 Forcing elements to be parsed as `block` elements when they are not by default could result in invalid HTML.
 
 For example, one could force a `<p>` element to be nested within another `<p>` element. In most cases, it is
 recommended to use the default behavior of `markdown="1"`.
-///
+:::
 
 
 ### `markdown="span"`
@@ -111,7 +110,8 @@ When the markdown attribute is set to "span", the parser will force span behavio
 
 The content of a span element is not parsed into block-level content. In other words, the content will not be rendered as paragraphs, headers, etc. Only inline syntax will be rendered, such as links, strong, emphasis, etc.
 
-/// example | Forced "span" markdown parsing
+:::: div example
+**Example: Forced "span" markdown parsing**
 
 ```md
 <div markdown="span">
@@ -127,14 +127,15 @@ renders as:
 </div>
 ```
 
-///
+::::
 
 
 ## Nesting
 
 When nesting multiple levels of raw HTML elements, a markdown attribute must be defined for each block-level element. For any block-level element that does not have a markdown attribute, everything inside that element is ignored, including child elements with markdown attributes.
 
-/// example | Markdown in nested HTML
+:::: div example
+**Example: Markdown in nested HTML
 
 ```md
 <article id="my-article" markdown="1">
@@ -175,3 +176,4 @@ renders as:
 </section>
 </article>
 ```
+::::

docs/content/markdown/tabs.md docs/content/directives/tabs.mddocs/content/markdown/tabs.md renamed to docs/content/directives/tabs.md

@@ -13,7 +13,7 @@
         ]
     },
     {
-        "path": "markdown.md",
+        "title": "Markdown",
         "pages": [
             "markdown/blocks.md",
             "markdown/formatting.md",
@@ -29,12 +29,19 @@
             },
             "markdown/code.md",
             "markdown/tables.md",
-            "markdown/admonitions.md",
             "markdown/attributes.md",
-            "markdown/tabs.md",
             # "markdown/html.md",
         ],
     },
+    {
+        "path": "directives/index.md",
+        "pages": [
+            "directives/admonitions.md",
+            "directives/figures.md",
+            "directives/tabs.md",
+            "directives/divs.md",
+        ],
+    },
     "autodoc.md",
     "languages.md",
     "versions.md",