Feature/add markdown plugins

.cache/pages.json

@@ -29,35 +29,14 @@
   },
   {
     "tags": [
-      "adTech",
       "apiDesign",
-      "articles",
-      "aws",
-      "case-studies",
-      "cd",
-      "ci",
       "cms",
       "code",
-      "contact",
       "crm",
-      "databaseNormalization",
-      "deployment",
-      "devPortals",
-      "express",
       "graphql",
-      "home",
-      "Joomla!",
-      "laravel",
-      "marTech",
       "online-learning",
-      "rails",
       "react",
-      "restful",
-      "scss",
       "services",
-      "site",
-      "sqlOptimization",
-      "testimonials",
       "typescript"
     ]
   }

.markdownlint.json

@@ -1,7 +1,10 @@
 {
+  "MD004": false,
   "MD013": false,
   "MD025": false,
+  "MD031": false,
   "MD033": false,
+  "MD035": false,
   "MD036": false,
   "MD041": false
 }

.markdownlintignore

@@ -0,0 +1 @@
+./src/content/articles/demo/index.mdx

.vscode/settings.json

@@ -37,6 +37,7 @@
     "fosstodon",
     "FOUC",
     "fprintf",
+    "gemoji",
     "glidejs",
     "gomodule",
     "GSAP",

@types/adobe__mdast-util-gridtables.d.ts

@@ -0,0 +1,7 @@
+declare module '@adobe/mdast-util-gridtables' {
+  export const TYPE_TABLE: 'gridTable'
+
+  // This is a mdast-util-to-hast handler factory; typing varies by mdast-util-to-hast version.
+  // Keep it permissive to avoid coupling tests/build to internal types.
+  export function mdast2hastGridTablesHandler(..._args: Array<unknown>): import('mdast-util-to-hast').Handler
+}

@types/adobe__remark-gridtables.d.ts

@@ -0,0 +1,9 @@
+declare module '@adobe/remark-gridtables' {
+  import type { Plugin } from 'unified'
+  import type { Root } from 'mdast'
+
+  type RemarkGridTablesOptions = Record<string, unknown>
+
+  const remarkGridTables: Plugin<[RemarkGridTablesOptions?], Root>
+  export default remarkGridTables
+}

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

@@ -0,0 +1,27 @@
+import type { Parent } from 'unist'
+
+declare module 'mdast' {
+  /** Custom node emitted by remark-captions / remark-attribution */
+  interface Figure extends Parent {
+    type: 'figure'
+    children: Array<RootContent>
+  }
+
+  /** Custom node emitted by remark-captions / remark-attribution */
+  interface Figcaption extends Parent {
+    type: 'figcaption'
+    children: Array<PhrasingContent>
+  }
+
+  /** Custom node emitted by `@adobe/remark-gridtables` */
+  interface GridTable extends Parent {
+    type: 'gridTable'
+    children: Array<RootContent>
+  }
+
+  interface RootContentMap {
+    figure: Figure
+    figcaption: Figcaption
+    gridTable: GridTable
+  }
+}

@types/remark-captions.d.ts

@@ -0,0 +1,15 @@
+declare module 'remark-captions' {
+  import type { Plugin } from 'unified'
+  import type { Root } from 'mdast'
+
+  export type RemarkCaptionsExternalNodeType = 'table' | 'code'
+  export type RemarkCaptionsInternalNodeType = 'blockquote' | 'image'
+
+  export interface RemarkCaptionsOptions {
+    external?: Partial<Record<RemarkCaptionsExternalNodeType, string>>
+    internal?: Partial<Record<RemarkCaptionsInternalNodeType, string>>
+  }
+
+  const remarkCaptions: Plugin<[RemarkCaptionsOptions?], Root>
+  export default remarkCaptions
+}

@types/remark-custom-blocks.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Type definitions for remark-custom-blocks
+ *
+ * The package does not currently ship TypeScript types.
+ */
+
+declare module 'remark-custom-blocks' {
+  import type { Plugin } from 'unified'
+  import type { Root } from 'mdast'
+
+  export type CustomBlockTitleRequirement = 'required' | 'optional' | 'none'
+
+  export type CustomBlockDefinition = {
+    classes?: string
+    title?: CustomBlockTitleRequirement
+    containerElement?: string
+    titleElement?: string
+    contentsElement?: string
+    details?: boolean
+  }
+
+  export type RemarkCustomBlocksOptions = Record<string, CustomBlockDefinition>
+
+  const remarkCustomBlocks: Plugin<[RemarkCustomBlocksOptions?] | [], Root>
+
+  export default remarkCustomBlocks
+}

_TODO.md

@@ -1,8 +1,6 @@
 <!-- markdownlint-disable-file -->
 # 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`**
-
-Adds `target="_blank" rel="noreferrer"` to all 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
 
-### 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 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)
+## Custom Directives
 
-Adds some custom directives:
+[`astro-directives`](https://github.com/QuentinDutot/astro-directives)
 
 ```react
 <Component client:hover />
@@ -197,87 +196,107 @@ Adds some custom directives:
 | client:hover  | element mouseover event                |
 | client:scroll | window scroll event                    |
 
-### [Prefetch](https://www.npmjs.com/package/@astrojs/prefetch) (**`installed`**)
-
-1. Add `rel="prefetch"` to any `<a />` tags to prefetch when visible
-2. Add `rel="prefetch-intent"` to any `<a />` links on your page to prefetch them only when they are hovered over, touched, or focused.
-
-## Stuff from ZMarkdown, a prepackaged Unified config
-
-Repo is in root of Corporate Websites
-
-- **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**
+## Prefetch Links
 
-  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.
+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.
 
-- **remark-abbr**
+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.
 
-  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`.
-
-- **remark-align**
-
-  This plugin parses custom Markdown syntax to center- or right-align elements.
-
-- **remark-captions**
+```html
+<a href="/about" data-astro-prefetch>
+<a href="/about" data-astro-prefetch="tap">About</a>
+```
 
-  Allow to add caption to such element as image, table or blockquote.
+If you want to prefetch all links, including those without the data-astro-prefetch attribute, you can set prefetch.prefetchAll to true:
 
-- **remark-comments**
+```typescript
+// astro.config.mjs
+import { defineConfig } from 'astro/config'
 
-  This plugin parses custom Markdown syntax for Markdown source comments.
+export default defineConfig({
+  prefetch: {
+    prefetchAll: true
+  }
+})
+```
 
-- **remark-custom-blocks**
+You can then opt-out of prefetching for individual links by setting data-astro-prefetch="false":
 
-  This plugin parses custom Markdown syntax to create new custom blocks.
+```html
+<a href="/about" data-astro-prefetch="false">About</a>
+```
 
-- **remark-escape--escaped**
+## Markdown
 
-  This plugin escapes HTML entities from Markdown input.
+## Code Block and Highlighting
 
-- **remark-grid-tables**
+## Astro includes shiki, tweak config
 
-  This plugin parses custom Markdown syntax to describe tables.
+### 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
 
-- **remark-heading-shift**
+[`astro-code-blocks`](https://www.npmjs.com/package/@thewebforge/astro-code-blocks)
 
-  Allows to shift heading to custimize the way you will integrate the generated tree inside your application.
 
-- **remark-heading-trailing-spaces**
-  This plugin removes trailing spaces from Markdown headers.
+#### Code tabs plugin so Javascript and Typescript examples can both be show.
 
-- **remark-iframes**
+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:
 
-  Allows to add `iframe` inclusion through `!(url)` code.
+```js [group:tabName]
+```
 
-- **remark-kbd**
+`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 <button> */
+  extraHtmlBeforeBtn: ``,
+  /** An HTML fragment included after <button> */
+  extraHtmlAfterBtn: ``,
+  /** Whether to show code language before the copy button */
+  showCodeLanguage: false,
+  /** Test to append after the copied text like a copyright notice */
+  attachText: ``,
+}
+```
 
-  This plugin parses custom Markdown syntax to handle keyboard keys.
+### rehype-mathjax and remark-math
 
-- **remark-numbered-footnotes**
+- `rehype-katex` is alternative but lacks accessibility
 
-  This plugin changes how [mdast][mdast] footnotes are displayed by using sequential numbers as footnote references instead of user-specified strings.
+```math
+L = \frac{1}{2} \rho v^2 S C_L
+```
 
-- **remark-sub-super**
 
-  This plugin parses custom Markdown syntax to handle subscript and superscript.
+### Mermaid JavaScript based diagramming and charting tool
 
-- **typographic-colon**
+```mermaid
+graph TD
+    A[Start] --> B{Is it working?}
+    B -->|Yes| C[Great!]
+    B -->|No| D[Debug]
+    D --> B
+```
 
-  Micro module to fix a common typographic issue that is hard to fix with most keyboard layouts.
+### Apache ECharts interactive charting and data visualization library for browser
 
-- **typographic-permille**
+@TODO: uses ES Modules, needs Jest config adjusted. See note in Mermaid plugin spec file.
 
-  Micro module to replace `%o` with `‰` and optionally replace the preceding space.
+`markdown-it-echarts`