do11y 0.2.2 → 0.2.4

package/README.md

@@ -2,9 +2,104 @@
 
 A bare-bones tool to document Vue components.
 
-- Write documentation in markdown files that turn into single file components.
-- Import markdown files as routes through `do11y:routes`.
-- Code blocks highlighted with [Shiki](https://shiki.style).
-- Import Vue files as highlighted code blocks through `.vue?shiki`, or `.vue?shiki&lang=css` (if you want the output to include the compiled style tags). These imports return a HTML string meaning you have to render the code block with `v-html`.
-- Create sandbox components - e.g. `Button.sandbox.vue` will be available under the url `/sandbox?id=button`, and if importing the component it will be wrapped inside an iframe component that has access to the source code with or without compiled CSS.
-- Easily document components through meta imports which give a simplified result from [vue-component-meta](https://www.npmjs.com/package/vue-component-meta) - e.g. `Button.vue?meta`.
+> [!WARNING]
+> This is a small personal project! I make a lot of component libraries for personal projects and I absolutely love, love, love writing documentation for components, and I intend for this to be a mix of some of the features I love from [VitePress](https://vitepress.dev) and [Histoire](https://histoire.dev). Issues and thoughts and contributions are very welcome! But it is, again, a _personal_ project 😊
+
+## Features
+
+### Markdown components with [@mdit-vue](https://github.com/mdit-vue/mdit-vue).
+
+Markdown files are treated as single file Vue components with the help of [@mdit-vue](https://github.com/mdit-vue/mdit-vue).
+
+You can customize the markdown-it instance through the `markdownSetup` option.
+
+### Import markdown route files as routes through `do11y:routes`
+
+To include a markdown file as a route it needs to have a `title` and a `slug` (e.g. `/button`) in it's frontmatter.
+
+### [Shiki](https://shiki.style) code highlighting
+
+Code blocks are automatically highlighted with [Shiki](https://shiki.style).
+
+You can customize the Shiki instance through the `highlighter` options.
+
+### Highlight imports
+
+You can import Vue files as highlighted code blocks through `.vue?highlight`, or `.vue?highlight&lang=css` (if you want the output to compile the style tags).
+
+These imports return HTML strings meaning you have to render the code block using `v-html`.
+
+> [!WARNING]
+> Imports of type `.vue?highlight&lang=css` only work on built sites. During development it will return the same result as `.vue?highlight`.
+
+### Sandboxes
+
+Create sandbox components - e.g. `Button.sandbox.vue` will be available under the url `/sandbox?id=button`, and if importing the component it will be wrapped inside an iframe component that has access to the components `?highlight` imports.
+
+To customize the sandbox app, use the `Sandbox` option - and to cutomize the iframe component used for import, use the `SandboxIframe` option.
+
+> [!NOTE]
+> The id is based on the filename - not the path to the file - this means if you have two sandbox files of the same name in different locations - they won't both work.
+
+### Document components with [vue-component-meta](https://www.npmjs.com/package/vue-component-meta)
+
+Document components through meta imports (`Button.vue?meta`) which give a simplified version of a result from [vue-component-meta](https://www.npmjs.com/package/vue-component-meta).
+
+## Options
+
+Expected as the default export in `docs/do11y/do11y.ts`.
+
+```ts
+interface Options {
+  /**
+   * The home page.
+   */
+  Home: () => Promise<Component>;
+
+  /**
+   * The layout for each route.
+   */
+  Layout?: () => Promise<Component>;
+
+  /**
+   * Additional setup for the app.
+   */
+  setup?(app: App, router: Router): void | Promise<void>;
+
+  /**
+   * The wrapper component for sandboxes.
+   */
+  Sandbox?: () => Promise<Component>;
+
+  /**
+   * Additional setup for the sandbox app.
+   */
+  setupSandbox?(app: App): void | Promise<void>;
+
+  /**
+   * Custom wrapper component for `.vue.sandbox` imports.
+   */
+  SandboxIframe?: () => Promise<Component>;
+
+  /**
+   * The code highlighter.
+   *   - Markdown code blocks
+   *   - `.vue?highlight` & `.vue?highlight&lang=css` imports
+   *   - `highlightedSource` and `highlightedCssSource` props in SandboxIframe
+   *
+   * If using multiple themes - you can set the `data-theme` attribute
+   * to switch between them, e.g. `data-theme="vitesse-light"`.
+   */
+  highlighter?: {
+    themes: (ThemeInput | StringLiteralUnion<BundledTheme, string>)[];
+    defaultTheme?: string | StringLiteralUnion<BundledTheme, string>;
+    transformers?: ShikiTransformer[];
+    postprocess?: (pre: HTMLPreElement) => void;
+  };
+
+  /**
+   * Additional markdown-it setup.
+   */
+  markdownSetup?: PluginSimple;
+}
+```

package/dist/docs/files.js

@@ -1,8 +1,10 @@
 import { join } from "node:path";
 import { searchForWorkspaceRoot } from "vite";
+const [_, __, ___, relativePath] = process.argv;
 export const ui = join(import.meta.dirname, "../ui");
-export const root = searchForWorkspaceRoot(process.cwd());
-// export const root = join(searchForWorkspaceRoot(process.cwd()), "example");
+export const root = relativePath
+    ? join(searchForWorkspaceRoot(process.cwd()), relativePath)
+    : searchForWorkspaceRoot(process.cwd());
 export const docs = join(root, "docs");
 export const output = join(docs, "dist");
 export const do11y = join(docs, "do11y", "do11y.ts");

package/dist/docs/options.js

@@ -20,9 +20,10 @@ const resolveOptions = async () => {
     return {
         ...options,
         highlighter: {
+            defaultTheme: options.highlighter?.defaultTheme || resolvedThemes[0],
             themes: options.highlighter?.themes ?? [],
             themesInput,
-            defaultTheme: options.highlighter?.defaultTheme || resolvedThemes[0],
+            transformers: options.highlighter?.transformers || [],
         },
     };
 };

package/dist/docs/plugins/highlight.js

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { parse as parseVue } from "vue/compiler-sfc";
 import { format } from "oxfmt";
 import { createHighlighter, bundledLanguages, bundledThemes } from "shiki";
+import { JSDOM } from "jsdom";
 import { do11yOptions } from "../options.js";
 import { transformerNotationDiff, transformerNotationErrorLevel, transformerNotationHighlight, } from "@shikijs/transformers";
 const shiki = await createHighlighter({
@@ -17,6 +18,16 @@ export const highlightCode = (code, lang) => {
             transformerNotationHighlight(),
             transformerNotationDiff(),
             transformerNotationErrorLevel(),
+            ...do11yOptions.highlighter.transformers,
+            {
+                name: "do11y",
+                postprocess(html) {
+                    const jsdom = new JSDOM(html);
+                    const preTag = jsdom.window.document.querySelector("pre");
+                    do11yOptions.highlighter.postprocess?.(preTag);
+                    return preTag.parentElement.innerHTML;
+                },
+            },
         ],
     });
 };
@@ -42,9 +53,11 @@ export default () => {
         async load(id) {
             if (id === "\0dolly:css.css") {
                 const generateThemeCss = (theme) => `
-          [data-theme="${theme}"] .shiki,
-          [data-theme="${theme}"] .shiki span {
+          [data-theme="${theme}"] .shiki {
             background-color: var(--shiki-${theme}-bg) !important;
+          }
+
+          [data-theme="${theme}"] .shiki span {
             color: var(--shiki-${theme}) !important;
           }
         `;

package/dist/docs/plugins/options.d.ts

@@ -1,15 +1,15 @@
 import type { Plugin } from "vite";
 import type { App, Component } from "vue";
 import type { Router } from "vue-router";
-import type { BundledTheme, StringLiteralUnion, ThemeInput } from "shiki";
+import type { BundledTheme, ShikiTransformer, StringLiteralUnion, ThemeInput } from "shiki";
 import type { MarkdownPluginOptions } from "./markdown.js";
 export interface Options extends MarkdownPluginOptions {
     /**
-     * The home page component.
+     * The home page.
      */
     Home: () => Promise<Component>;
     /**
-     * The layout component for the documents.
+     * The layout for each route.
      */
     Layout?: () => Promise<Component>;
     /**
@@ -17,7 +17,7 @@ export interface Options extends MarkdownPluginOptions {
      */
     setup?(app: App, router: Router): void | Promise<void>;
     /**
-     * The wrapper component for the sandbox.
+     * The wrapper component for sandboxes.
      */
     Sandbox?: () => Promise<Component>;
     /**
@@ -25,7 +25,7 @@ export interface Options extends MarkdownPluginOptions {
      */
     setupSandbox?(app: App): void | Promise<void>;
     /**
-     * Custom wrapper component for `?iframe` imports.
+     * Custom wrapper component for `.vue.sandbox` imports.
      */
     SandboxIframe?: () => Promise<Component>;
     /**
@@ -40,6 +40,8 @@ export interface Options extends MarkdownPluginOptions {
     highlighter?: {
         themes: (ThemeInput | StringLiteralUnion<BundledTheme, string>)[];
         defaultTheme?: string | StringLiteralUnion<BundledTheme, string>;
+        transformers?: ShikiTransformer[];
+        postprocess?: (pre: HTMLPreElement) => void;
     };
 }
 export interface ResolvedOptions extends Omit<Options, "highlighter"> {
@@ -47,6 +49,8 @@ export interface ResolvedOptions extends Omit<Options, "highlighter"> {
         themes: (ThemeInput | StringLiteralUnion<BundledTheme, string>)[];
         themesInput: Record<string, string>;
         defaultTheme: string;
+        transformers: ShikiTransformer[];
+        postprocess?: (pre: HTMLPreElement) => void;
     };
 }
 /**

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "do11y",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "A bare-bones tool to document Vue components.",
+  "keywords": [
+    "docs-generator",
+    "markdown",
+    "shiki",
+    "story",
+    "vite",
+    "vue"
+  ],
   "license": "MIT",
   "repository": "github:sq11y/do11y",
   "bin": "./dist/docs/cli.js",
@@ -25,6 +33,7 @@
     "@shikijs/langs": "^3.22.0",
     "@shikijs/themes": "^3.22.0",
     "@shikijs/transformers": "^3.22.0",
+    "@types/markdown-it": "^14.1.2",
     "front-matter": "^4.0.2",
     "jsdom": "^28.1.0",
     "markdown-it": "^14.1.1",
@@ -38,7 +47,6 @@
   "devDependencies": {
     "@tsconfig/node24": "^24.0.4",
     "@types/jsdom": "^27.0.0",
-    "@types/markdown-it": "^14.1.2",
     "@types/markdown-it-attrs": "^4.1.3",
     "@types/node": "24.10.3",
     "@vue/tsconfig": "^0.8.1",