From 8dcc4712171768403384d5fcc549fd18bf54c3e9 Mon Sep 17 00:00:00 2001 From: Kevin Brown Date: Mon, 15 Dec 2025 16:09:33 +0300 Subject: [PATCH 01/28] Move directories in markdown tests folder --- .vscode/settings.json | 1 + _TODO.md | 382 ++++++++++++++++-- src/content/articles/demo/index.mdx | 99 ++++- src/lib/markdown/README.md | 324 +-------------- .../e2e => }/__fixtures__/abbreviations.md | 0 .../e2e => }/__fixtures__/attributes.md | 0 .../e2e => }/__fixtures__/attribution.md | 0 .../{__tests__/e2e => }/__fixtures__/emoji.md | 0 .../e2e => }/__fixtures__/full-pipeline.md | 0 src/lib/markdown/__tests__/coverage.spec.ts | 20 +- .../__tests__/e2e/MARKDOWN_TESTING.md | 140 ------- .../rehypeAccessibleEmojis.spec.tsx | 4 +- .../rehypeAutolinkHeadings.spec.tsx | 4 +- .../rehypeTailwindClasses.spec.tsx | 4 +- .../remarkAbbreviations.spec.tsx | 4 +- .../remarkAttributes.spec.tsx | 4 +- .../remarkAttribution.spec.tsx | 4 +- .../remarkBreaks.spec.tsx | 4 +- .../{unifiedPlugins => }/remarkEmoji.spec.tsx | 4 +- .../remarkLinkifyRegex.spec.tsx | 4 +- .../remarkReplacements.spec.tsx | 4 +- .../markdown/__tests__/integration/README.md | 44 ++ .../rehype-accessible-emojis-astro.spec.ts | 0 .../rehype-autolink-headings-astro.spec.ts | 0 .../rehype-tailwind-astro.spec.ts | 0 .../rehype-tailwind-classes-astro.spec.ts | 0 ...ype-tailwind-simple-elements-astro.spec.ts | 0 .../remark-abbreviations-astro.spec.ts | 0 .../remark-attributes-astro.spec.ts | 0 .../remark-attribution-astro.spec.ts | 0 .../remark-breaks-astro.spec.ts | 0 .../remark-emoji-astro.spec.ts | 0 .../remark-linkify-regex-astro.spec.ts | 0 .../remark-replacements-astro.spec.ts | 0 .../units_with_default_astro/README.md | 97 ----- src/lib/markdown/helpers/markdownLoader.tsx | 2 +- 36 files changed, 516 insertions(+), 633 deletions(-) rename src/lib/markdown/{__tests__/e2e => }/__fixtures__/abbreviations.md (100%) rename src/lib/markdown/{__tests__/e2e => }/__fixtures__/attributes.md (100%) rename src/lib/markdown/{__tests__/e2e => }/__fixtures__/attribution.md (100%) rename src/lib/markdown/{__tests__/e2e => }/__fixtures__/emoji.md (100%) rename src/lib/markdown/{__tests__/e2e => }/__fixtures__/full-pipeline.md (100%) delete mode 100644 src/lib/markdown/__tests__/e2e/MARKDOWN_TESTING.md rename src/lib/markdown/__tests__/e2e/{unifiedPlugins => }/rehypeAccessibleEmojis.spec.tsx (94%) rename src/lib/markdown/__tests__/e2e/{unifiedPlugins => }/rehypeAutolinkHeadings.spec.tsx (94%) rename src/lib/markdown/__tests__/e2e/{unifiedPlugins => }/rehypeTailwindClasses.spec.tsx (95%) rename src/lib/markdown/__tests__/e2e/{unifiedPlugins => }/remarkAbbreviations.spec.tsx (95%) rename src/lib/markdown/__tests__/e2e/{unifiedPlugins => }/remarkAttributes.spec.tsx (92%) rename src/lib/markdown/__tests__/e2e/{unifiedPlugins => }/remarkAttribution.spec.tsx (96%) rename src/lib/markdown/__tests__/e2e/{unifiedPlugins => }/remarkBreaks.spec.tsx (92%) rename src/lib/markdown/__tests__/e2e/{unifiedPlugins => }/remarkEmoji.spec.tsx (91%) rename src/lib/markdown/__tests__/e2e/{unifiedPlugins => }/remarkLinkifyRegex.spec.tsx (91%) rename src/lib/markdown/__tests__/e2e/{unifiedPlugins => }/remarkReplacements.spec.tsx (93%) create mode 100644 src/lib/markdown/__tests__/integration/README.md rename src/lib/markdown/__tests__/{units_with_default_astro => integration}/rehype-accessible-emojis-astro.spec.ts (100%) rename src/lib/markdown/__tests__/{units_with_default_astro => integration}/rehype-autolink-headings-astro.spec.ts (100%) rename src/lib/markdown/__tests__/{units_with_default_astro => integration}/rehype-tailwind-astro.spec.ts (100%) rename src/lib/markdown/__tests__/{units_with_default_astro => integration}/rehype-tailwind-classes-astro.spec.ts (100%) rename src/lib/markdown/__tests__/{units_with_default_astro => integration}/rehype-tailwind-simple-elements-astro.spec.ts (100%) rename src/lib/markdown/__tests__/{units_with_default_astro => integration}/remark-abbreviations-astro.spec.ts (100%) rename src/lib/markdown/__tests__/{units_with_default_astro => integration}/remark-attributes-astro.spec.ts (100%) rename src/lib/markdown/__tests__/{units_with_default_astro => integration}/remark-attribution-astro.spec.ts (100%) rename src/lib/markdown/__tests__/{units_with_default_astro => integration}/remark-breaks-astro.spec.ts (100%) rename src/lib/markdown/__tests__/{units_with_default_astro => integration}/remark-emoji-astro.spec.ts (100%) rename src/lib/markdown/__tests__/{units_with_default_astro => integration}/remark-linkify-regex-astro.spec.ts (100%) rename src/lib/markdown/__tests__/{units_with_default_astro => integration}/remark-replacements-astro.spec.ts (100%) delete mode 100644 src/lib/markdown/__tests__/units_with_default_astro/README.md diff --git a/.vscode/settings.json b/.vscode/settings.json index 791c694a1..3516c3ae1 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -37,6 +37,7 @@ "fosstodon", "FOUC", "fprintf", + "gemoji", "glidejs", "gomodule", "GSAP", diff --git a/_TODO.md b/_TODO.md index 4088ed156..529619c7a 100644 --- a/_TODO.md +++ b/_TODO.md @@ -1,8 +1,6 @@ # TODO -continue - ## Refactor API Endpoints to Astro Actions ### Action / Domain / Responder Pattern @@ -73,7 +71,7 @@ If we want to make it feel less inconsistent, we could either (a) rename `_logge ## Mobile Social Shares UI -See the example image in Social Shares. +See the example image in Social Shares. The social shares UI on mobile should be a modal that slides in from the bottom. ## Performance @@ -83,10 +81,20 @@ Implement mitigations in test/e2e/specs/07-performance/PERFORMANCE.md Vercel Analytics +- Highlighter component +- Social Shares component +- Social Embeds: Track embed interactions +- Cookie Consent +- Download Form component + +npm i @vercel/analytics +import Analytics from '@vercel/analytics/astro' +https://vercel.com/docs/analytics/quickstart#add-the-analytics-component-to-your-app + ## Themepicker tooltips, extra themes - Add additional themes -- Add tooltip that makes use of the description field +- Add tooltip that makes use of the description field for the theme, explaining what the intent of the theme is ## Sentry feedback, chat bot tying into my phone and email @@ -157,35 +165,26 @@ Google Calendar, Apple Calendar, Yahoo Calender, Microsoft 365, Outlook, and T Needs to add real API key and test -## Astro 3rd-Party Integrations, Eleventy Migration - -### **`eleventy-plugin-external-links`** +- Get API token from webmention.io +- Add WEBMENTION_IO_TOKEN to .env +- (Optional) Set up Bridgy for social media +- Test with sample webmentions -Adds `target="_blank" rel="noreferrer"` to all external links - -### Astro wrapper for the `@github/clipboard-copy-element` web component. Copies element text content or input values to the clipboard +## Astro wrapper for the `@github/clipboard-copy-element` web component. Copies element text content or input values to the clipboard [`clipboard-copy`](https://github.com/BryceRussell/astro-github-elements/tree/main/packages/clipboard-copy#astro-github-elementsclipboard-copy) -### Astro wrapper for GitHub's relative time web component. Translates dates to past or future time phrases, like "*4 hours from now*" or "*20 days ago*" +## Astro wrapper for GitHub's relative time web component. Translates dates to past or future time phrases, like "*4 hours from now*" or "*20 days ago*" [Relative Time](https://github.com/BryceRussell/astro-github-elements/tree/main/packages/time#readme) -### Display text in a circular layout +## Display text in a circular layout [TextCircle](https://github.com/LoStisWorld/astro-textcircle#astro-textcircle) -## Markdown +## Custom Directives -### Custom version of the code block integration from Astro Docs. "Beautiful code blocks for your Astro site". Applied to the code blocks created in `.mdx` files - -[`astro-code-blocks`](https://www.npmjs.com/package/@thewebforge/astro-code-blocks) - -## Miscellaneous - -### [`astro-directives`](https://github.com/QuentinDutot/astro-directives) - -Adds some custom directives: +[`astro-directives`](https://github.com/QuentinDutot/astro-directives) ```react @@ -197,32 +196,106 @@ Adds some custom directives: | client:hover | element mouseover event | | client:scroll | window scroll event | -### [Prefetch](https://www.npmjs.com/package/@astrojs/prefetch) (**`installed`**) +## Prefetch Links + +The default prefetch strategy when adding the data-astro-prefetch attribute is hover. To change it, you can configure prefetch.defaultStrategy in your astro.config.mjs file. + +hover (default): Prefetch when you hover over or focus on the link. +tap: Prefetch just before you click on the link. +viewport: Prefetch as the links enter the viewport. +load: Prefetch all links on the page after the page is loaded. + +```html + +About +``` + +If you want to prefetch all links, including those without the data-astro-prefetch attribute, you can set prefetch.prefetchAll to true: + +```typescript +// astro.config.mjs +import { defineConfig } from 'astro/config' + +export default defineConfig({ + prefetch: { + prefetchAll: true + } +}) +``` + +You can then opt-out of prefetching for individual links by setting data-astro-prefetch="false": + +```html +About +``` + +## Markdown + +Plugins already in stack: + +- `remark-breaks` - Line break handling +- `remark-emoji` - Emoji shortcode conversion +- `remark-linkify-regex` - URL auto-linking + +- `rehype-accessible-emojis` - Emoji accessibility attributes +- `rehype-autolink-headings` + +Custom plugins: -1. Add `rel="prefetch"` to any `` tags to prefetch when visible -2. Add `rel="prefetch-intent"` to any `` links on your page to prefetch them only when they are hovered over, touched, or focused. +- `remark-abbreviations` - Abbreviation expansion +- `remark-attributes` - Custom attributes on elements +- `remark-attribution` - Blockquote attributions +- `remark-replacements` - Heading anchor links -## Stuff from ZMarkdown, a prepackaged Unified config +- `rehype-tailwind` - Add custom CSS classes to Markdown-generated elements in this file -Repo is in root of Corporate Websites + +### Markdown Not Working + +- color tabs like GFM when using HEX, RGB, or HSL values in backticks. This should generate a callout box around the hex color with a dot to the right showing the color. +- Section link anchor icons +- GFM Alert syntax doesn't work +- Markdown E2E tests on demo test page fixture +- Move GFM to our stack and turn it off in Astro. That way we can customize it and remove the middle layer of integration unit tests. That way the only change Astro will make is adding IDs to headings for TOC links. +- Astro also includes remark-smartypants and shiki +- We're adding 'rehype-autolink-headings', but Astro does too: https://docs.astro.build/en/guides/markdown-content/#heading-ids-and-plugins + +### Custom version of the code block integration from Astro Docs. "Beautiful code blocks for your Astro site". Applied to the code blocks created in `.mdx` files + +[`astro-code-blocks`](https://www.npmjs.com/package/@thewebforge/astro-code-blocks) + +### rehype-external-links + +npm install rehype-external-links + +Adds `target="_blank" rel="noreferrer"` to all external links in Markdown files + +```typescript +rehypePlugins: [ + [ + rehypeExternalLinks, + { + target: '_blank', + rel: ['noopener', 'noreferrer'], + }, + ], +] +``` - **mdast-util-split-by-heading** A MDAST tool to split a markdown tree into list of subtrees representing the chapters. It relies on heading depth. -- **rebber** +- **LATEX** - transformation of MDAST into `latex` code. This code must be included inside a custom latex to be compiled. - Have a look at `https://github.com/zestedesavoir/latex-template/blob/master/zmdocument.cls` to get a working example. + rebber - transformation of MDAST into `latex` code. This code must be included inside a custom latex to be compiled. + + Have a look at `https://github.com/zestedesavoir/latex-template/blob/master/zmdocument.cls` to get a working example. - **remark-abbr** This plugin parses `*[ABBR]: abbr definition` and then replace all ABBR instance in text with a new MDAST node so that `rehype` can parse it into `abbr` html tag. -- **rehype-footnotes-title** - - This plugin adds a `title` attribute to the footnote links, mainly for accessibility purpose. - - **rehype-html-blocks** This plugin wraps (multi-line) raw HTML in `p`. @@ -270,10 +343,16 @@ Repo is in root of Corporate Websites This plugin changes how [mdast][mdast] footnotes are displayed by using sequential numbers as footnote references instead of user-specified strings. +- **rehype-footnotes-title** + + This plugin adds a `title` attribute to the footnote links, mainly for accessibility purpose. + - **remark-sub-super** This plugin parses custom Markdown syntax to handle subscript and superscript. +- **Also underline.** + - **typographic-colon** Micro module to fix a common typographic issue that is hard to fix with most keyboard layouts. @@ -281,3 +360,238 @@ Repo is in root of Corporate Websites - **typographic-permille** Micro module to replace `%o` with `‰` and optionally replace the preceding space. + +- **KATEX** + +Math markup + +### Details/Summary elements + +These HTML elements aren't being processed by remarkGfm (they need to be raw HTML). Expandable and collapsible content using HTML
and elements. + +`rehype-details` + +### Add ==highlighted== syntax + +1. add remark-mark plugin +2. Remove skip from integration test in + +### Add accessible name to section in footnotes plugin + + const markdownFootnoteBlockOpen = () => + '
\n' + + '
\n' + + '
    \n' + +### Code tabs plugin so Javascript and Typescript examples can both be show. + +There can only be white space between two code blocks. Display name is set by `tabName` and can only contain characters in [A-Za-z0-9_]. Syntax for the first line of the code block is: + +```js [group:tabName] +``` + +`markdown-it-codetabs` + +### Add copy button to code blocks + +`markdown-it-copy` + +Options for "copy" button added to code blocks + +```javascript +const markdownCodeCopyConfig = { + /** Text shown on copy button */ + btnText: `Copy`, + /** Text shown on copy failure */ + failText: `Copy Failed`, + /** Text shown on copy success */ + successText: `Success!`, // 'copy success' | copy-success text + /** Amount of time to show success message */ + successTextDelay: 2000, + /** An HTML fragment included before