Add markdown settings file

markdown-it.settings.js files can be added to domstack websites and they
let you customize or replace the markdownit instance.

Author: bcomnes

README.md

@@ -934,6 +934,59 @@ export default async function esbuildSettingsOverride (esbuildSettings) {
 }
 ```
 
+### `markdown-it.settings.js`
+
+This is an optional file you can create anywhere.
+It should export a default sync or async function that accepts a single argument (the markdown-it instance configured by domstack) and returns a modified markdown-it instance.
+Use this to add custom markdown-it plugins or modify the parser configuration.
+Here are some examples:
+
+```js
+// Add custom plugins
+import markdownItContainer from 'markdown-it-container'
+import markdownItPlantuml from 'markdown-it-plantuml'
+
+export default async function markdownItSettingsOverride (md) {
+  // Add custom plugins
+  md.use(markdownItContainer, 'spoiler', {
+    validate: function(params) {
+      return params.trim().match(/^spoiler\s+(.*)$/)
+    },
+    render: function (tokens, idx) {
+      const m = tokens[idx].info.trim().match(/^spoiler\s+(.*)$/)
+      if (tokens[idx].nesting === 1) {
+        return '<details><summary>' + md.utils.escapeHtml(m[1]) + '</summary>\n'
+      } else {
+        return '</details>\n'
+      }
+    }
+  })
+  
+  md.use(markdownItPlantuml)
+  
+  return md
+}
+```
+
+```js
+// Replace with a completely new instance
+import markdownIt from 'markdown-it'
+
+export default async function markdownItSettingsOverride (md) {
+  // Create a new instance with different settings
+  const newMd = markdownIt({
+    html: false,        // Disable HTML tags in source
+    breaks: true,       // Convert \n to <br>
+    linkify: false,     // Disable auto-linking
+  })
+  
+  // Add only the plugins you want
+  newMd.use(myCustomPlugin)
+  
+  return newMd
+}
+```
+
 ## Variables
 
 Pages, Layouts, and `postVars` all receive an object with the following parameters:

examples/markdown-settings/README.md

@@ -0,0 +1,73 @@
+# Markdown-it Settings Example
+
+This example demonstrates how to customize the markdown-it instance used for rendering Markdown content in DOMStack using the `markdown-it.settings.js` file.
+
+## Features
+
+- Custom containers for warnings, info boxes, and collapsible sections
+- Custom styling for code blocks
+- Example of how to add and configure markdown-it plugins
+
+## How it Works
+
+DOMStack now supports a `markdown-it.settings.js` file that allows you to customize the markdown-it instance. This file should export a default function that receives the default markdown-it instance and returns a modified instance.
+
+```js
+export default async function markdownItSettingsOverride (md) {
+  // Add plugins
+  md.use(somePlugin)
+  
+  // Customize renderers
+  md.renderer.rules.someRule = function (tokens, idx, options, env, renderer) {
+    // Custom rendering logic
+  }
+  
+  return md
+}
+```
+
+## Running the Example
+
+1. Clone the repository
+2. Run `npm install` from the project root
+3. Navigate to this example directory: `cd examples/markdown-settings`
+4. Run `npm run build` to build the site
+5. Open `dist/index.html` in your browser to see the results
+
+## What to Look For
+
+- `src/markdown-it.settings.js` - This file customizes the markdown-it instance with custom containers
+- `src/page.md` - This file demonstrates the custom markdown syntax
+- `src/style.css` - Contains styles for the custom containers
+
+## Custom Container Examples
+
+The example includes three custom containers:
+
+### Warning Container
+
+```markdown
+::: warning Security Notice
+This is a custom warning container.
+:::
+```
+
+### Info Container
+
+```markdown
+::: info Did you know?
+This is a custom info container.
+:::
+```
+
+### Details Container (Collapsible)
+
+```markdown
+::: details Click to expand
+This content is hidden by default.
+:::
+```
+
+## Further Customization
+
+You can add any markdown-it plugin or customize the rendering of any markdown element by modifying the `markdown-it.settings.js` file. This provides a powerful way to extend the markdown capabilities of your DOMStack site.

examples/markdown-settings/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "markdown-settings-example",
+  "version": "1.0.0",
+  "description": "Example demonstrating markdown-it.settings.js usage",
+  "type": "module",
+  "scripts": {
+    "build": "domstack build src dist",
+    "dev": "domstack dev src"
+  },
+  "devDependencies": {
+    "domstack": "workspace:*",
+    "markdown-it-container": "^4.0.0",
+    "markdown-it-admonition": "^1.0.4"
+  }
+}

examples/markdown-settings/src/markdown-it.settings.js

@@ -0,0 +1,66 @@
+import markdownItContainer from 'markdown-it-container'
+
+/**
+ * Customize the markdown-it instance with additional plugins
+ * @param {import('markdown-it')} md - The markdown-it instance
+ * @returns {import('markdown-it')} - The modified markdown-it instance
+ */
+export default async function markdownItSettingsOverride (md) {
+  // Add custom container for warnings
+  md.use(markdownItContainer, 'warning', {
+    validate: function (params) {
+      return params.trim().match(/^warning\s*(.*)$/)
+    },
+    render: function (tokens, idx) {
+      const m = tokens[idx].info.trim().match(/^warning\s*(.*)$/)
+      if (tokens[idx].nesting === 1) {
+        const title = (m && m.length > 1) ? m[1] : 'Warning'
+        return '<div class="custom-warning">\n<div class="warning-title">' + md.utils.escapeHtml(title) + '</div>\n<div class="warning-content">\n'
+      } else {
+        return '</div>\n</div>\n'
+      }
+    }
+  })
+
+  // Add custom container for info boxes
+  md.use(markdownItContainer, 'info', {
+    validate: function (params) {
+      return params.trim().match(/^info\s*(.*)$/)
+    },
+    render: function (tokens, idx) {
+      const m = tokens[idx].info.trim().match(/^info\s*(.*)$/)
+      if (tokens[idx].nesting === 1) {
+        const title = (m && m.length > 1) ? m[1] : 'Info'
+        return '<div class="custom-info">\n<div class="info-title">' + md.utils.escapeHtml(title) + '</div>\n<div class="info-content">\n'
+      } else {
+        return '</div>\n</div>\n'
+      }
+    }
+  })
+
+  // Add custom container for collapsible sections
+  md.use(markdownItContainer, 'details', {
+    validate: function (params) {
+      return params.trim().match(/^details\s+(.*)$/)
+    },
+    render: function (tokens, idx) {
+      const m = tokens[idx].info.trim().match(/^details\s+(.*)$/)
+      if (tokens[idx].nesting === 1) {
+        return '<details>\n<summary>' + md.utils.escapeHtml(m[1]) + '</summary>\n<div class="details-content">\n'
+      } else {
+        return '</div>\n</details>\n'
+      }
+    }
+  })
+
+  // Customize existing renderer - add custom classes to code blocks
+  md.renderer.rules.code_block = function (tokens, idx, options, env, renderer) {
+    const token = tokens[idx]
+    const content = token.content
+    const langName = token.info || ''
+
+    return `<pre class="custom-code-block"><code class="language-${langName}">${md.utils.escapeHtml(content)}</code></pre>\n`
+  }
+
+  return md
+}

examples/markdown-settings/src/page.md

@@ -0,0 +1,77 @@
+---
+title: Markdown-it Settings Example
+layout: root
+---
+
+# Markdown-it Settings Example
+
+This page demonstrates custom markdown-it plugins configured via `markdown-it.settings.js`.
+
+## Custom Containers
+
+### Warning Container
+
+::: warning Security Notice
+This is a custom warning container. It can be used to highlight important security information or other warnings.
+:::
+
+::: warning
+This warning uses the default title.
+:::
+
+### Info Container
+
+::: info Did you know?
+Custom containers can make your documentation more expressive and easier to scan.
+:::
+
+::: info
+Info boxes are great for tips and additional context.
+:::
+
+### Details Container
+
+::: details Click to expand more information
+This content is hidden by default and can be revealed by clicking the summary.
+
+You can include any markdown content here:
+- Lists
+- **Bold text**
+- `code snippets`
+- And more!
+:::
+
+::: details Advanced Configuration
+The `markdown-it.settings.js` file allows you to:
+1. Add custom plugins
+2. Modify existing renderers
+3. Configure parser options
+4. Create entirely new markdown syntaxes
+:::
+
+## Custom Code Block Styling
+
+The code blocks below have custom classes applied:
+
+```javascript
+// This code block has a custom class
+const greeting = "Hello from custom markdown-it settings!";
+console.log(greeting);
+```
+
+```python
+# Python code also gets the custom treatment
+def greet(name):
+    return f"Hello, {name}!"
+```
+
+## How It Works
+
+The `markdown-it.settings.js` file exports a function that receives the default markdown-it instance and returns a modified version. This allows you to:
+
+- Add third-party plugins
+- Create custom containers
+- Override default renderers
+- Configure parsing options
+
+Check out the `markdown-it.settings.js` file in this example to see how these customizations are implemented.

examples/markdown-settings/src/root.layout.js

@@ -0,0 +1,17 @@
+export default function rootLayout ({ title, styles, scripts, children }) {
+  return /* html */ `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${title || 'Markdown-it Settings Example'}</title>
+  ${styles.map(style => `<link rel="stylesheet" href="${style}">`).join('\n  ')}
+</head>
+<body>
+  <main>
+    ${children}
+  </main>
+  ${scripts.map(script => `<script type="module" src="${script}"></script>`).join('\n  ')}
+</body>
+</html>`
+}