Fix header spacing in Markdown, padding inside code tabs

Author: webstackdev

_TODO.md

@@ -156,6 +156,7 @@ COAK has two pricing tiers:
 - /search
 - /tags/[tag]
 - Bug reporter modal
+- Email templates
 
 ## Keyboard Navigation
 
@@ -197,3 +198,19 @@ We have generated detailed outlines for each of the MDX proposed articles we hav
 Act as a principal software engineer. Your goal is to write a detailed technical article based on the provided outline. Context: The target audience is Senior DevOps and infrastructure Engineers. The tone should be authoritative, professional, and concise, avoiding fluff or filler words. Think step-by-step before writing to improve the accuracy of technical explanations. Use a friendly first-person voice. Anything that reads like generic marketing copy is not what we want but we still want the effect of being "real" and approachable - try not to sound like technical documentation. We want to show empathy for our readers.
 
 Let's work through each article section by section based on the H2 headers in the outline. If the section looks good as-is, I'll just type "ok" so you know to continue to the next section.
+
+## Stylings
+
+- More space below headings
+- Better appearance of details and summary elements. The styling in rehype-tailwind is applying to the detail and summary elements generated by remark-custom-blocks.
+- Better list styling and decoration markers
+- Remove dotted underline from abbr elements? Or some other way of indicating abbreviations?
+- [Link](url) [[color=pink target=_blank .centered]] is not picking up styles
+- We have remark-mark-plus to create marked text like ==mark me==. Is the Highlighter component our social highlighter?
+- Search icon is too large now
+- Make sure underline style in Core Markdown section is correct
+- Are we using breakpoints correctly - isn't iPhone wider than our `sm` breakpoint?
+- Mermaid theming, horizontal layout for desktop, vertical for mobile, using groups like in Code Tabs to add the media selectors e.g. `[g1:desktop]`
+
+`graph TD`: Top-to-Bottom (Vertical).
+`graph LR`: Left-to-Right (Horizontal).

src/content/articles/demo/index.mdx

@@ -29,6 +29,78 @@ Nested blockquotes:
 >
 >> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
 
+#### Blockquotes with internal remark-attribution plugin
+
+The plugin allows to provide an attribution for a quotation:
+
+```markdown
+> That's one small step for [a] man, one giant leap for mankind.
+> — Neil Armstrong (1969, July 21)
+```
+
+> That's one small step for [a] man, one giant leap for mankind.
+> — Neil Armstrong (1969, July 21)
+
+Compiles to the following HTML:
+
+```html
+The generated markup is not only accessible for screen readers but allows you to style the attribution line however you like:
+
+<figure class="c-blockquote">
+  <blockquote>
+    <p>
+      That's one small step for [a] man, one giant leap for mankind.
+    </p>
+  </blockquote>
+  <figcaption class="c-blockquote__attribution">
+    Neil Armstrong (1969, July 21)
+  </figcaption>
+</figure>
+```
+
+#### Blockquotes with remark-captions
+
+By default it wraps the elements code, image, table and blockquote in a `<figure>` element, and adds a `<figcaption>` block as the last child. You can configure it to work on other elements by changing the keywords.
+
+**Blockquote caption**
+
+```markdown
+> Some blockquote text that will have a caption
+> Source: The caption text that will appear under the blockquote
+```
+
+> Some blockquote text that will have a caption
+> Source: The caption text that will appear under the blockquote
+
+Compiles to the following HTML:
+
+```html
+<figure class="my-8 mx-auto max-w-none text-center">
+  <blockquote class="border-l-2 border-blue-600 my-8 pl-14 -ml-4 font-serif text-2xl italic">
+    <p class="mb-8 leading-relaxed">
+      Some blockquote text that will have a caption
+    </p>
+  </blockquote>
+  <figcaption class="text-base italic pt-3">
+    The caption text that will appear under the blockquote
+  </figcaption>
+</figure>
+```
+
+### Detail and Summary
+
+```markdown
+<details>
+  <summary>Details</summary>
+  Something small enough to escape casual notice.
+</details>
+```
+
+<details>
+  <summary>Details</summary>
+  Something small enough to escape casual notice.
+</details>
+
 ### Horizontal Rules
 
 Asterisks (`***`):
@@ -53,6 +125,10 @@ _________________
 
 Linked image:
 
+```markdown
+[![An old rock in the desert](/assets/images/shiprock.svg "Shiprock placeholder")](https://www.flickr.com/photos/beaurogers/31833779864/in/photolist-Qv3rFw-34mt9F-a9Cmfy-5Ha3Zi-9msKdv-o3hgjr-hWpUte-4WMsJ1-KUQ8N-deshUb-vssBD-6CQci6-8AFCiD-zsJWT-nNfsgB-dPDwZJ-bn9JGn-5HtSXY-6CUhAL-a4UTXB-ugPum-KUPSo-fBLNm-6CUmpy-4WMsc9-8a7D3T-83KJev-6CQ2bK-nNusHJ-a78rQH-nw3NvT-7aq2qf-8wwBso-3nNceh-ugSKP-4mh4kh-bbeeqH-a7biME-q3PtTf-brFpgb-cg38zw-bXMZc-nJPELD-f58Lmo-bXMYG-bz8AAi-bxNtNT-bXMYi-bXMY6-bXMYv)
+```
+
 [![An old rock in the desert](/assets/images/shiprock.svg "Shiprock placeholder")](https://www.flickr.com/photos/beaurogers/31833779864/in/photolist-Qv3rFw-34mt9F-a9Cmfy-5Ha3Zi-9msKdv-o3hgjr-hWpUte-4WMsJ1-KUQ8N-deshUb-vssBD-6CQci6-8AFCiD-zsJWT-nNfsgB-dPDwZJ-bn9JGn-5HtSXY-6CUhAL-a4UTXB-ugPum-KUPSo-fBLNm-6CUmpy-4WMsc9-8a7D3T-83KJev-6CQ2bK-nNusHJ-a78rQH-nw3NvT-7aq2qf-8wwBso-3nNceh-ugSKP-4mh4kh-bbeeqH-a7biME-q3PtTf-brFpgb-cg38zw-bXMZc-nJPELD-f58Lmo-bXMYG-bz8AAi-bxNtNT-bXMYi-bXMY6-bXMYv)
 
 ### `kbd`
@@ -200,6 +276,8 @@ Should compile to the following HTML:
 implemented by <a href="https://github.com/remarkjs/remark">remark</a></p>
 ```
 
+This plugin works on MDAST, a Markdown AST implemented by [remark](https://github.com/remarkjs/remark).
+
 ### rehype-accessible-emojis
 
 There is a doc listing all available emojis in the /docs directory.
@@ -236,35 +314,71 @@ This custom plugin parses custom Markdown syntax to center- or right-align eleme
 
 ```markdown
 [center]paragraph[/center]
-
-[right]paragraph[/right]
 ```
 
 [center]A centered paragraph[/center]
 
-[right]A right-aligned paragraph[/right]
+```markdown
+[right]paragraph[/right]
+```
 
-Block elements can be wrapped with their own tags to apply `flex flex-col items-end` or `flex flex-col items-center` classes:
+[right]A right-aligned paragraph[/right]
 
 ```markdown
 [center]
+
 > My blockquote
+
 [/center]
 ```
 
 [center]
 
 > My blockquote
 
+[/center]
+
+```markdown
+[center]
+
+- a
+- b
+
+[/center]
+```
+
+[center]
+
 - a
 - b
 
 [/center]
 
+```markdown
 [right]
 
 > My blockquote
 
+[/right]
+```
+
+[right]
+
+> My blockquote
+
+[/right]
+
+```markdown
+[right]
+
+- a
+- b
+
+[/right]
+```
+
+[right]
+
 - a
 - b
 
@@ -275,9 +389,9 @@ Block elements can be wrapped with their own tags to apply `flex flex-col items-
 Add HTML attributes to supported Markdown elements using a MDX-safe doubled-square-bracket postfix syntax:
 
 ```markdown
-### Heading [[.my-class #my-id]]
 ![Image](/assets/images/shiprock.svg) [[width=300 .centered]]
-[Link](url) [[.btn target=_blank]]
+
+[Link](url) [[color=pink target=_blank .centered]]
 ```
 
 ![Image](/assets/images/shiprock.svg) [[width=300 .centered]]
@@ -316,15 +430,7 @@ The generated markup is not only accessible for screen readers but allows you to
 
 By default it wraps the elements code, image, table and blockquote in a `<figure>` element, and adds a `<figcaption>` block as the last child. You can configure it to work on other elements by changing the keywords.
 
-**Blockquote caption**
-
-```markdown
-> Some blockquote text that will have a caption
-> Source: The caption text that will appear under the blockquote
-```
-
-> Some blockquote text that will have a caption
-> Source: The caption text that will appear under the blockquote
+__Blockquote example is moved to the Blockquote section.__
 
 **Code caption**
 
@@ -415,20 +521,6 @@ The string `L = \frac{1}{2} \rho v^2 S C_L` within a fenced code black set to la
 L = \frac{1}{2} \rho v^2 S C_L
 ```
 
-### remark-supersub
-
-Subscript and superscript text
-
-```markdown
-~subscript~, e.g. a~i~
-
-^superscript^, e.g. e^x^
-```
-
-Subscript: a~i~
-
-Superscript: e^x^
-
 ### remark-video
 
 Embed videos in HTML5 markup that are in the `/public` folder
@@ -1258,13 +1350,15 @@ The references can be anywhere in the document, before or after their use:
 
 ## Core Markdown
 
+Subscript and superscript text is from `remark-supersub`.
+
 | Style | Syntax | Keyboard shortcut | Example | Output |
 | --- | --- | --- | --- | --- |
 | Bold | `** **` | Command+B (Mac) or Ctrl+B (Windows/Linux) | `**This is bold text**` | **This is bold text** |
 | Italic | `_ _` | Command+I (Mac) or Ctrl+B (Windows/Linux) | `_This text is italicized_` | _This text is italicized_ |
 | Strikethrough | `~~ ~~` or `~ ~` | None | `~~This was mistaken text~~` | ~~This was mistaken text~~ |
 | Bold and nested italic | `** **` and `_ _` | None | `**This text is _extremely_ important**` | **This text is \*extremely\* important** |
 | All bold and italic | `*** ***` | None | `**_All this text is important_**` | **_All this text is important_** |
-| Subscript | `<sub> </sub>` | None | `This is a <sub>subscript</sub> text` | This is a <sub>subscript</sub> |
-| Superscript | `<sup> </sup>` | None | `This is a <sup>superscript</sup> text` | This is a <sup>superscript</sup> text |
-| Underline | `<ins> </ins>` | None | `This is an <ins>underlined</ins> text` | This is an <ins>underlined</ins> text |
+| Subscript | `~subscript~` | None | `This is a ~subscript~ text` | This is a ~subscript~ |
+| Superscript | `^superscript^` | None | `This is a ^superscript^ text` | This is a ^superscript^ text |
+| Underline | `__   __` | None | `This is an __underlined__ text` | This is an __underlined__ text |

src/lib/config/markdown.ts

@@ -279,10 +279,16 @@ export const remarkCustomBlocksConfig = {
 
 /** remark-captions plugin (explicit defaults from upstream README) */
 export const remarkCaptionsConfig = {
+  /**
+   * Caption is rendered outside the captioned element or inside its wrapping paragraph
+   */
   external: {
     table: 'Table:',
     code: 'Code:',
   },
+  /**
+   * Caption is rendered inside the captioned element or inside its wrapping paragraph
+   */
   internal: {
     blockquote: 'Source:',
     image: 'Figure:',

src/lib/markdown/plugins/rehype-tailwind/index.ts

@@ -67,9 +67,8 @@ export function rehypeTailwindClasses() {
       if (['h2', 'h3', 'h4'].includes(node.tagName)) {
         node.properties = node.properties || {}
         node.properties['className'] = ((node.properties['className'] as string[]) || []).concat([
-          'mb-2',
-          'mt-6',
           'relative',
+          'my-6',
           /**
            * Remove top margin from first child element of headings since we're
            * controlling bottom margin here.
@@ -103,32 +102,18 @@ export function rehypeTailwindClasses() {
         ])
       }
 
-
-      /**
-       * Code blocks (pre > code) stylings with responsive margins
-       */
-      if (node.tagName === 'pre') {
-        node.properties = node.properties || {}
-        node.properties['className'] = ((node.properties['className'] as string[]) || []).concat([
-          'block',
-          'text-base',
-          'px-4',
-          'py-4',
-          'bg-page-base-offset',
-          'mb-6',
-        ])
-      }
-
       /**
-       * Code blocks (pre > code.language-text) should wrap text instead of forcing horizontal scrolling.
-       * This keeps the existing <pre> styles but allows future styling specifically for text blocks.
+       * Non-Code Tabs Text Code blocks (pre > code.language-text) should wrap text
+       * instead of forcing horizontal scrolling. This keeps the existing <pre>
+       * styles but allows future styling specifically for text blocks.
        */
       if (node.tagName === 'code' && hasClass(node, 'language-text')) {
         const parent = getParent(node)
 
         if (isHastElement(parent) && parent.tagName === 'pre') {
           node.properties = node.properties || {}
           node.properties['className'] = ((node.properties['className'] as string[]) || []).concat([
+            'my-2',
             'whitespace-pre-wrap',
             'break-words',
           ])
@@ -146,10 +131,29 @@ export function rehypeTailwindClasses() {
       if (node.tagName === 'code-tabs') {
         node.properties = node.properties || {}
         node.properties['className'] = ((node.properties['className'] as string[]) || []).concat([
+          'block',
+          'border-page-base-offset',
           'border',
-          'border-gray-200',
-          'rounded-md',
+          'max-w-full',
+          'mb-4',
+          'min-w-0',
           'overflow-hidden',
+          'rounded-md',
+          'w-full',
+        ])
+      }
+
+      /**
+       * Code blocks (pre > code) stylings with responsive margins
+       */
+      if (node.tagName === 'pre') {
+        node.properties = node.properties || {}
+        node.properties['className'] = ((node.properties['className'] as string[]) || []).concat([
+          'block',
+          'bg-page-base-offset',
+          'max-w-full',
+          'pr-3',
+          'py-3',
         ])
       }
 
@@ -231,13 +235,7 @@ export function rehypeTailwindClasses() {
         ])
       }
 
-      /**
-       * =============================================================================
-       *
-       * Attribution Blockquote Stylings
-       *
-       * =============================================================================
-       */
+      /** Attribution Blockquote Stylings */
       if (node.tagName === 'figure' && hasClass(node, 'c-blockquote')) {
         node.properties = node.properties || {}
         node.properties['className'] = ((node.properties['className'] as string[]) || []).concat([