Improve style of ordered and unordered lists

Author: webstackdev

.patch-tool-add-test

@@ -0,0 +1 @@
+ok2

_TODO.md

@@ -202,12 +202,55 @@ Let's work through each article section by section based on the H2 headers in th
 ## Stylings
 
 - 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?
+- remark-mark-plus highlight color needs adjusted. 
+- Highlighter component not rendering social share modal on hover and focus.
 - 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]`
+- Add scroll bar under header to show how far down you are on the page while reading
+
+## Add theming to Mermaid
+
+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).
+
+`strategy: 'pre-mermaid'` in Mermaid config in `astro.config.ts`
+
+This strategy replaces the element with a <pre class="mermaid"> element with only the diagram as its child. Given the example, this yields:
+
+```html
+<html>
+  <head>
+    <meta charset="utf-8" />
+  </head>
+  <body>
+    <pre class="mermaid">
+      graph TD;
+          A-->B;
+          A-->C;
+          B-->D;
+          C-->D;
+    </pre>
+    <pre class="mermaid">
+      graph TD;
+          A-->B;
+          A-->C;
+          B-->D;
+          C-->D;
+    </pre>
+  </body>
+</html>
+```
+
+This allows Mermaid to render the diagram on the client side, for example using:
+
+````typescript
+import mermaid from 'mermaid'
+
+mermaid.initialize({ startOnLoad: true })
+```
+
+[rerender diagrams when I switched color-scheme](https://github.com/mermaid-js/mermaid/issues/1945)
+[mermaid init](https://github.com/hbstack/mermaid/blob/main/assets/hb/modules/mermaid/init.ts)
+[theming](https://mermaid.ai/open-source/config/theming.html)

package-lock.json

@@ -165,6 +165,7 @@
     "lit": "^3.3.2",
     "markdownlint-cli2": "^0.20.0",
     "md-attr-parser": "^1.3.0",
+    "mermaid": "^11.12.2",
     "nanostores": "^1.1.0",
     "nodemailer": "^7.0.12",
     "npm": "^11.7.0",

package.json

@@ -13,50 +13,6 @@ import Demo from '@components/Test/Demo.mdx'
 
 ## Components (looping)
 
-### Images
-
-```markdown
-![Octocat](https://myoctocat.com/assets/images/base-octocat.svg)
-```
-
-![Octocat](https://myoctocat.com/assets/images/base-octocat.svg)
-
-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`
-
-This is a default HTML markup, just adding it here to not forget to use it when needed:
-
-```markdown
-<p>
-  You can also create a new document by pressing the
-  <kbd><kbd>Ctrl</kbd>+<kbd>N</kbd></kbd> shortcut.
-</p>
-```
-
-<p>
-  You can also create a new document by pressing the
-  <kbd><kbd>Ctrl</kbd>+<kbd>N</kbd></kbd> shortcut.
-</p>
-
-### Links
-
-```markdown
-My favorite search engine is [Duck Duck Go](https://duckduckgo.com).
-
-Visit our [homepage](/) or read more [articles](/articles) to explore additional content.
-```
-
-My favorite search engine is [Duck Duck Go](https://duckduckgo.com).
-
-Visit our [homepage](/) or read more [articles](/articles) to explore additional content.
-
 ### Lists
 
 Unordered lists:
@@ -1414,3 +1370,49 @@ Dashes (`---`):
 Underscores ()`___`):
 
 _________________
+
+### Images
+
+Use a relative path from the folder if the image is in src/assets (e.g. `../../../assets/images/typescript-downloadable-icon.png`) and will be optimized in the build. Images in the public folder are not optimized and can be referenced with an absolute path like `shiprock.svg` below.
+
+```markdown
+![Shiprock](/assets/images/shiprock.svg)
+```
+
+![Shiprock](/assets/images/shiprock.svg)
+
+Linked image:
+
+```markdown
+[![Shiprock](/assets/images/shiprock.svg "Shiprock placeholder")](/contact)
+```
+
+[![Shiprock](/assets/images/shiprock.svg "Shiprock placeholder")](/contact)
+
+### `kbd`
+
+This is a default HTML markup, just adding it here to not forget to use it when needed:
+
+```markdown
+<p>
+  You can also create a new document by pressing the
+  <kbd><kbd>Ctrl</kbd>+<kbd>N</kbd></kbd> shortcut.
+</p>
+```
+
+<p>
+  You can also create a new document by pressing the
+  <kbd><kbd>Ctrl</kbd>+<kbd>N</kbd></kbd> shortcut.
+</p>
+
+### Links
+
+```markdown
+My favorite search engine is [Duck Duck Go](https://duckduckgo.com).
+
+Visit our [homepage](/) or read more [articles](/articles) to explore additional content.
+```
+
+My favorite search engine is [Duck Duck Go](https://duckduckgo.com).
+
+Visit our [homepage](/) or read more [articles](/articles) to explore additional content.

src/content/articles/demo/index.mdx

@@ -47,6 +47,20 @@ function expectHasAtLeastOneValidClassAttribute(element: Element | null): void {
   })
 }
 
+function expectClassTokensAreWellFormedIfPresent(element: Element | null): void {
+  expect(element).toBeTruthy()
+  if (!element) return
+
+  const classAttr = element.getAttribute('class')
+  if (!classAttr) return
+
+  const tokens = splitClassTokens(classAttr)
+  expect(tokens.length).toBeGreaterThan(0)
+  tokens.forEach(token => {
+    expect(isWellFormedCssClassToken(token)).toBe(true)
+  })
+}
+
 let html: string
 
 beforeAll(async () => {
@@ -107,18 +121,21 @@ describe('Layer 3: E2E - rehypeTailwindClasses', () => {
     expectHasAtLeastOneValidClassAttribute(paragraph)
   })
 
-  it('should add Tailwind classes to lists', () => {
+  it('should wrap markdown lists for scoped styling', () => {
     const { container } = render(<MarkdownOutput html={html} />)
 
-    const list = container.querySelector('ul')
-    expectHasAtLeastOneValidClassAttribute(list)
+    const listWrapper = container.querySelector('div.markdown-list')
+    expectHasAtLeastOneValidClassAttribute(listWrapper)
+
+    const list = listWrapper?.querySelector('ul')
+    expect(list).toBeTruthy()
   })
 
-  it('should add Tailwind classes to list items', () => {
+  it('should keep list items semantic (classes optional)', () => {
     const { container } = render(<MarkdownOutput html={html} />)
 
     const listItem = container.querySelector('li')
-    expectHasAtLeastOneValidClassAttribute(listItem)
+    expectClassTokensAreWellFormedIfPresent(listItem)
   })
 
   it('should add Tailwind classes to code elements', () => {

src/lib/markdown/__tests__/e2e/rehype-tailwind-classes.spec.tsx

@@ -49,7 +49,8 @@ describe('rehype-tailwind-classes (Layer 2: With Astro Pipeline)', () => {
       })
 
       expect(html).toContain('<ul')
-      expect(html).toMatch(/class="[^"]*list-/)
+      expect(html).toMatch(/<div class="markdown-list[^\"]*">\s*<ul/)
+      expect(html).toMatch(/contains-task-list|task-list-item/)
     })
   })
 
@@ -68,7 +69,8 @@ Text with footnote[^1]
       })
 
       expect(html).toContain('class=')
-      expect(html).toMatch(/mb-8|text-lg/)
+      expect(html).toMatch(/class="[^"]*mb-/)
+      expect(html).toMatch(/<div class="markdown-list[^\"]*">\s*<ol>/)
     })
   })
 

src/lib/markdown/__tests__/integration/rehype-tailwind-classes-astro.spec.ts

@@ -47,7 +47,12 @@ function expectHasAtLeastOneValidClassAttribute(element: Element | null, name: s
 }
 
 async function renderMarkdownToDocument(markdown: string): Promise<Document> {
-  const html = await processWithAstroSettings({ markdown, plugin: rehypeTailwindClasses, stage: 'rehype' })
+  const html = await processWithAstroSettings({
+    markdown,
+    plugin: rehypeTailwindClasses,
+    stage: 'rehype',
+  })
+
   return new JSDOM(html).window.document
 }
 
@@ -68,14 +73,19 @@ describe('rehypeTailwindClasses (Layer 2: Astro Pipeline) - simple elements', ()
     expectHasAtLeastOneValidClassAttribute(starred.querySelector('hr'), 'hr (***)')
   })
 
-  it('adds at least one class to <ul>, <ol>, and <li> elements', async () => {
-    const document = await renderMarkdownToDocument(['- Item 1', '- Item 2', '', '1. First', '2. Second'].join('\n'))
+  it('wraps top-level lists in a .markdown-list container', async () => {
+    const markdown = ['- Item 1', '- Item 2', '', '1. First', '2. Second'].join('\n')
+    const document = await renderMarkdownToDocument(markdown)
 
-    expectHasAtLeastOneValidClassAttribute(document.querySelector('ul'), 'ul')
-    expectHasAtLeastOneValidClassAttribute(document.querySelector('ol'), 'ol')
+    const listWrappers = Array.from(document.querySelectorAll('div.markdown-list'))
+    expect(listWrappers.length).toBeGreaterThanOrEqual(2)
+    listWrappers.forEach((wrapper, index) => {
+      expectHasAtLeastOneValidClassAttribute(wrapper, `div.markdown-list[${index}]`)
+    })
 
-    const firstListItem = document.querySelector('li')
-    expectHasAtLeastOneValidClassAttribute(firstListItem, 'li')
+    expect(document.querySelector('ul')).toBeTruthy()
+    expect(document.querySelector('ol')).toBeTruthy()
+    expect(document.querySelector('li')).toBeTruthy()
   })
 
   it('adds at least one class to <table>, <th>, and <td> elements', async () => {
@@ -95,9 +105,19 @@ describe('rehypeTailwindClasses (Layer 2: Astro Pipeline) - simple elements', ()
 
   it('does not emit malformed class tokens anywhere', async () => {
     const document = await renderMarkdownToDocument(
-      ['# Heading', '', 'Paragraph text.', '', '- List item', '', '---', '', '| A | B |', '| --- | --- |', '| 1 | 2 |'].join(
-        '\n'
-      )
+      [
+        '# Heading',
+        '',
+        'Paragraph text.',
+        '',
+        '- List item',
+        '',
+        '---',
+        '',
+        '| A | B |',
+        '| --- | --- |',
+        '| 1 | 2 |',
+      ].join('\n')
     )
 
     const withClass = Array.from(document.querySelectorAll('[class]'))

src/lib/markdown/__tests__/integration/rehype-tailwind-simple-elements-astro.spec.ts

@@ -31,7 +31,7 @@ describe('remark-captions (Layer 2: Astro Pipeline)', () => {
       pluginOptions: remarkCaptionsConfig,
     })
 
-    expect(html.match(/<figure>/g)?.length).toBeGreaterThanOrEqual(4)
+    expect(html.match(/<figure>/g)?.length).toBeGreaterThanOrEqual(3)
     expect(html).toContain('Quote caption')
     expect(html).toContain('Table caption')
     expect(html).toContain('Code caption')

src/lib/markdown/__tests__/integration/remark-captions-astro.spec.ts

@@ -70,21 +70,15 @@ describe('htmlElements configuration', () => {
 
   test('includes all expected element types', () => {
     const expectedElements = [
-      'p',
-      'img',
-      'video',
-      'figure',
-      'figcaption',
+      'details',
       'hr',
-      'ul',
-      'ol',
-      'li',
+      'img',
       'mark',
+      'summary',
       'table',
       'th',
       'td',
-      'summary',
-      'details',
+      'video',
     ]
 
     expectedElements.forEach(tagName => {
@@ -213,9 +207,9 @@ describe('isSimpleHtmlElement', () => {
 
 describe('getElementConfig', () => {
   test('returns config for valid tag name', () => {
-    const config = getElementConfig('p')
+    const config = getElementConfig('img')
     expect(config).toBeDefined()
-    expect(config?.tagName).toBe('p')
+    expect(config?.tagName).toBe('img')
     expect(Array.isArray(config?.classes)).toBe(true)
     expect((config?.classes || []).length).toBeGreaterThan(0)
     ;(config?.classes || []).forEach(classToken => {