Update stylings on blockquotes

Author: webstackdev

@types/mdast-extensions-figures-and-gridtables.d.ts

@@ -1,13 +1,13 @@
 import type { Parent } from 'unist'
 
 declare module 'mdast' {
-  /** Custom node emitted by remark-captions / remark-attribution */
+  /** Custom node emitted by remark-captions / remark-blockquote */
   interface Figure extends Parent {
     type: 'figure'
     children: Array<RootContent>
   }
 
-  /** Custom node emitted by remark-captions / remark-attribution */
+  /** Custom node emitted by remark-captions / remark-blockquote */
   interface Figcaption extends Parent {
     type: 'figcaption'
     children: Array<PhrasingContent>

_TODO.md

@@ -201,13 +201,11 @@ Let's work through each article section by section based on the H2 headers in th
 
 ## 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]`

src/content/articles/demo/index.mdx

@@ -15,6 +15,8 @@ import Demo from '@components/Test/Demo.mdx'
 
 ### Blockquotes
 
+Quotation marks are added by CSS, so should not be included on the blockquote text.
+
 > This is a blockquote. Use it for quotes, citations, or to highlight important statements from external sources.
 
 Nested blockquotes:
@@ -29,9 +31,9 @@ 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
+__Blockquotes with attribution__
 
-The plugin allows to provide an attribution for a quotation:
+The pluginwill provide an attribution for a quotation if it is prefixed with an em dash. To include a date, put them in trailing parentheses:
 
 ```markdown
 > That's one small step for [a] man, one giant leap for mankind.
@@ -41,26 +43,32 @@ The plugin allows to provide an attribution for a quotation:
 > That's one small step for [a] man, one giant leap for mankind.
 > — Neil Armstrong (1969, July 21)
 
+```markdown
+> That's one small step for [a] man, one giant leap for mankind.
+> — Neil Armstrong
+```
+
+> Nothing inspires forgiveness quite like revenge.
+> — Scott Adams
+
 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">
+<figure class="blockquote">
   <blockquote>
     <p>
       That's one small step for [a] man, one giant leap for mankind.
     </p>
   </blockquote>
-  <figcaption class="c-blockquote__attribution">
+  <figcaption class="blockquote-attribution">
     Neil Armstrong (1969, July 21)
   </figcaption>
 </figure>
 ```
 
-#### Blockquotes with remark-captions
+__Blockquotes with 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.
+For blockquotes, captions are handled by the internal `remark-blockquote` plugin so they can be combined with an attribution.
 
 **Blockquote caption**
 
@@ -72,16 +80,46 @@ By default it wraps the elements code, image, table and blockquote in a `<figure
 > Some blockquote text that will have a caption
 > Source: The caption text that will appear under the blockquote
 
-Compiles to the following HTML:
+Compiles to the following HTML (ignoring styles):
 
 ```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">
+<figure class="blockquote-figure">
+  <blockquote>
+    <p>
       Some blockquote text that will have a caption
     </p>
   </blockquote>
-  <figcaption class="text-base italic pt-3">
+  <figcaption class="blockquote-caption">
+    The caption text that will appear under the blockquote
+  </figcaption>
+</figure>
+```
+
+__Blockquotes with both attribution and caption__
+
+```markdown
+> That's one small step for [a] man, one giant leap for mankind.
+> — Neil Armstrong (1969, July 21)
+> Source: The caption text that will appear under the blockquote
+```
+
+> That's one small step for [a] man, one giant leap for mankind.
+> — Neil Armstrong (1969, July 21)
+> Source: The caption text that will appear under the blockquote
+
+Should compile to the following HTML:
+
+```html
+<figure class="blockquote-figure">
+  <blockquote>
+    <p>
+      That's one small step for [a] man, one giant leap for mankind.
+    </p>
+  </blockquote>
+  <div class="blockquote-attribution">
+    Neil Armstrong (1969, July 21)
+  </div>
+  <figcaption class="blockquote-caption">
     The caption text that will appear under the blockquote
   </figcaption>
 </figure>
@@ -397,9 +435,9 @@ Add HTML attributes to supported Markdown elements using a MDX-safe doubled-squa
 ![Image](/assets/images/shiprock.svg) [[width=300 .centered]]
 [Link Example](/testing/markdown) [[.btn target=_blank]]
 
-### remark-attribution
+### remark-blockquote
 
-The plugin allows to provide an attribution for a quotation:
+The plugin allows you to provide an attribution for a quotation:
 
 ```markdown
 > That's one small step for [a] man, one giant leap for mankind.
@@ -412,36 +450,34 @@ The plugin allows to provide an attribution for a quotation:
 Should compile 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">
+<figure class="blockquote">
   <blockquote>
     <p>
       That's one small step for [a] man, one giant leap for mankind.
     </p>
   </blockquote>
-  <figcaption class="c-blockquote__attribution">
+  <figcaption class="blockquote-attribution">
     Neil Armstrong (1969, July 21)
   </figcaption>
 </figure>
 ```
 
 ### 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 example is moved to the Blockquote section.__
+By default it wraps the elements code, image, and table 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.
 
 **Code caption**
 
+The caption line is prefixed with `Code:` and added below the code block with no blank line:
+
 ```ts
 export const answer = 42
 ```
 Code: This caption appears under the code block
 
 **Table caption**
 
-Note: a blank line is required before `Table:` so it parses as a paragraph after the table.
+Note: a blank line is required before tje `Table:` prefixed line so it parses as a paragraph after the table.
 
 ```markdown
 | a | b |
@@ -459,7 +495,7 @@ Table: This caption appears under the table
 
 **Image caption**
 
-Note: the `Figure:` caption must be in the same paragraph as the image (no blank line).
+Note: the `Figure:` prefixed line must be in the same paragraph as the image (no blank line).
 
 ```markdown
 ![Wordmark](/assets/images/branding/wordmark.svg)

src/icons/search.svg

@@ -112,8 +112,8 @@ Object.defineProperty(remarkAbbreviations, 'name', { value: 'remarkAbbreviations
 import remarkAttributes from '../markdown/plugins/remark-attributes'
 Object.defineProperty(remarkAttributes, 'name', { value: 'remarkAttributes' })
 
-import remarkAttribution from '../markdown/plugins/remark-attribution'
-Object.defineProperty(remarkAttribution, 'name', { value: 'remarkAttribution' })
+import remarkBlockquote from '../markdown/plugins/remark-blockquote'
+Object.defineProperty(remarkBlockquote, 'name', { value: 'remarkBlockquote' })
 
 import remarkAlign from '../markdown/plugins/remark-align'
 Object.defineProperty(remarkAlign, 'name', { value: 'remarkAlign' })
@@ -277,21 +277,23 @@ export const remarkCustomBlocksConfig = {
   },
 } as const
 
-/** remark-captions plugin (explicit defaults from upstream README) */
+/**
+ * remark-captions plugin
+ *
+ * NOTE: This plugin's options are `external` and `internal`.
+ * We intentionally disable its built-in blockquote handling so our
+ * `remarkBlockquote` plugin owns blockquote caption/attribution semantics.
+ */
 export const remarkCaptionsConfig = {
-  /**
-   * Caption is rendered outside the captioned element or inside its wrapping paragraph
-   */
   external: {
-    table: 'Table:',
     code: 'Code:',
+    table: 'Table:',
   },
-  /**
-   * Caption is rendered inside the captioned element or inside its wrapping paragraph
-   */
   internal: {
-    blockquote: 'Source:',
     image: 'Figure:',
+    // Prevent remark-captions from wrapping blockquotes (default is 'Source:').
+    // Blockquotes are handled by `remarkBlockquote` instead.
+    blockquote: '__BLOCKQUOTE_CAPTIONS_DISABLED__',
   },
 } as const
 
@@ -319,7 +321,7 @@ export const remarkRehypeConfig: RemarkRehypeOptions = {
   /** Convert GridTables mdast nodes to standard HTML table output */
   handlers: {
     [TYPE_TABLE]: mdast2hastGridTablesHandler(),
-    // remark-captions + remark-attribution emit mdast nodes with type "figure"/"figcaption".
+    // remark-captions + remark-blockquote emit mdast nodes with type "figure"/"figcaption".
     // Without explicit handlers, mdast-util-to-hast may flatten block children (notably `code`) and drop captions.
     figure: (state: MdastToHastState, node: unknown) => {
       return {
@@ -374,7 +376,7 @@ export const markdownConfig: Partial<MdxOptions> = {
     remarkSupersub,
     /** Highlights via ==marked== */
     remarkMarkPlus,
-    /** Captions for code, images, tables, and blockquotes */
+    /** Captions for code, images, and tables */
     [remarkCaptions, remarkCaptionsConfig],
     /** Definition lists (PHP Markdown Extra style) */
     remarkDeflist,
@@ -390,8 +392,8 @@ export const markdownConfig: Partial<MdxOptions> = {
      * Example: [text content]{.class #id attr=value} creates <span> with attributes
      */
     [remarkAttributes, remarkAttributesConfig],
-    /** Wrap blockquotes with attribution in semantic figure/figcaption markup */
-    remarkAttribution,
+    /** Wrap blockquotes with caption/attribution in semantic figure markup */
+    remarkBlockquote,
     /** Convert emoji syntax like :heart: to emoji images */
     remarkEmoji,
     /** Support generic directive syntax (required by remark-video) */

src/lib/config/markdown.ts

@@ -0,0 +1,26 @@
+---
+title: Blockquote Test
+---
+
+<!-- markdownlint-disable -->
+
+# Blockquote Feature Test
+
+## Attribution
+
+> That's one small step for man, one giant leap for mankind.
+> — Neil Armstrong
+
+> The best way to predict the future is to invent it.
+> — Alan Kay
+
+## Caption
+
+> Some blockquote text that will have a caption
+> Source: The caption text that will appear under the blockquote
+
+## Caption and attribution
+
+> That's one small step for man, one giant leap for mankind.
+> — Neil Armstrong (1969, July 21)
+> Source: The caption text that will appear under the blockquote

src/lib/markdown/__fixtures__/attribution.md

@@ -33,7 +33,7 @@ describe('Layer 4: E2E - Full Pipeline Integration', () => {
       // Verify all plugins contributed to the output
       expect(html).toContain('<abbr') // Abbreviations
       expect(html).toContain('class="custom-link"') // Attributes
-      expect(html).toContain('class="c-blockquote') // Attribution
+      expect(html).toContain('class="blockquote') // Blockquote attribution/caption
       expect(html).toContain('❤️') // Emoji
       expect(html).toContain('href="https://www.webstackbuilders.com"') // Auto-linking
       expect(html).toContain('class="anchor-link') // Anchor headings