do11y 0.1.2 → 0.2.3

package/README.md

@@ -2,7 +2,101 @@
 
 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`.
-- 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`.
+## 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 to be in file `docs/do11y/do11y.ts`.
+
+```ts
+export 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/index.d.ts

@@ -16,16 +16,17 @@ export interface SandboxIframeProps {
      */
     url: string;
     /**
-     * The source code.
+     * HTML string containing the highlighted source code.
      *
      * @do11y Automatically passed.
      */
-    source?: string;
+    highlightedSource: string;
     /**
-     * The source code with compiled CSS.
-     * Only included if the style tag has lang `scss` or `sass`.
+     * HTML string containing the highlighted source code,
+     * with all the style tags compiled to CSS.
      *
      * @do11y Automatically passed.
+     * @caveat Only works in a built solution - during development this returns the same as `highlightedSource`.
      */
-    sourceWithCompiledCss?: string;
+    highlightedCssSource: string;
 }

package/dist/docs/options.d.ts

@@ -1,5 +1,5 @@
-import type { Options } from "./plugins/options.js";
+import type { ResolvedOptions } from "./plugins/options.js";
 /**
- * Access plugin options (`docs/do11y/index.ts`).
+ * Access plugin options (`docs/do11y/do11y.ts`).
  */
-export declare const do11yOptions: Options;
+export declare const do11yOptions: ResolvedOptions;

package/dist/docs/options.js

@@ -1,5 +1,33 @@
 import { do11y } from "./files.js";
+const resolveOptions = async () => {
+    const options = (await import(do11y)).default;
+    const themes = options.highlighter?.themes.map(async (theme) => {
+        if (typeof theme === "string") {
+            return theme;
+        }
+        else {
+            const resolvedTheme = await (typeof theme === "function" ? await theme() : theme);
+            return "default" in resolvedTheme ? resolvedTheme.default.name : resolvedTheme.name;
+        }
+    });
+    /* prettier-ignore */
+    let resolvedThemes = (await Promise.all(themes ?? [])).filter((theme) => !!theme);
+    if (!resolvedThemes.length) {
+        resolvedThemes = ["vitesse-light", "vitesse-black", "vitesse-dark"];
+    }
+    const themesInput = {};
+    resolvedThemes.forEach((theme) => (themesInput[theme] = theme));
+    return {
+        ...options,
+        highlighter: {
+            defaultTheme: options.highlighter?.defaultTheme || resolvedThemes[0],
+            themes: options.highlighter?.themes ?? [],
+            themesInput,
+            transformers: options.highlighter?.transformers || [],
+        },
+    };
+};
 /**
- * Access plugin options (`docs/do11y/index.ts`).
+ * Access plugin options (`docs/do11y/do11y.ts`).
  */
-export const do11yOptions = (await import(do11y)).default;
+export const do11yOptions = await resolveOptions();

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

@@ -0,0 +1,9 @@
+import type { Plugin } from "vite";
+export declare const highlightCode: (code: string, lang: string) => string;
+export declare const highlightAndFormatCode: (path: string, code: string) => Promise<string>;
+/**
+ * Adds `.vue?highlight` imports which returns the
+ * highlighted code from Shiki.
+ */
+declare const _default: () => Plugin;
+export default _default;

package/dist/docs/plugins/highlight.js

@@ -0,0 +1,103 @@
+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({
+    langs: Object.keys(bundledLanguages),
+    themes: [...Object.values(bundledThemes), ...do11yOptions.highlighter.themes],
+});
+export const highlightCode = (code, lang) => {
+    return shiki.codeToHtml(code, {
+        lang,
+        themes: do11yOptions.highlighter.themesInput,
+        defaultColor: do11yOptions.highlighter.defaultTheme,
+        transformers: [
+            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;
+                },
+            },
+        ],
+    });
+};
+export const highlightAndFormatCode = async (path, code) => {
+    return highlightCode((await format(path, code)).code, "vue");
+};
+/**
+ * Adds `.vue?highlight` imports which returns the
+ * highlighted code from Shiki.
+ */
+export default () => {
+    let viteDevServer;
+    return {
+        name: "do11y:shiki",
+        configureServer(server) {
+            viteDevServer = server;
+        },
+        async resolveId(id) {
+            if (id === "do11y:css") {
+                return "\0dolly:css.css";
+            }
+        },
+        async load(id) {
+            if (id === "\0dolly:css.css") {
+                const generateThemeCss = (theme) => `
+          [data-theme="${theme}"] .shiki {
+            background-color: var(--shiki-${theme}-bg) !important;
+          }
+
+          [data-theme="${theme}"] .shiki span {
+            color: var(--shiki-${theme}) !important;
+          }
+        `;
+                return Object.keys(do11yOptions.highlighter.themesInput)
+                    .filter((theme) => do11yOptions.highlighter.defaultTheme !== theme)
+                    .map((theme) => generateThemeCss(theme))
+                    .join("\n");
+            }
+            else if (id.endsWith(".vue?highlight") || id.endsWith(".vue?highlight&lang=css")) {
+                const path = id.replace("?highlight", "").replace("&lang=css", "");
+                const source = readFileSync(path, "utf-8");
+                /**
+                 * Getting the code from `load` does not work during development,
+                 * so we return the original code during development.
+                 *
+                 * We also return the original code if the import does not specifically ask
+                 * to compile the style tags to CSS.
+                 */
+                if (viteDevServer?.config.command === "serve" || !id.endsWith("lang=css")) {
+                    return `export default ${JSON.stringify(await highlightAndFormatCode(path, source))};`;
+                }
+                const loadCss = async (index, lang) => {
+                    const { code } = await this.load({
+                        id: path + `?vue&type=style&index=${index}&lang.${lang}?inline`,
+                    });
+                    return code?.replace(/^(export default ")/, "").replace(/"$/, "");
+                };
+                const sourceWithoutStyles = source.replace(/\n<style\b[^>]*>[\s\S]*?<\/style>/gi, "");
+                const stylesheets = parseVue(source).descriptor.styles.map((style, i) => {
+                    /* prettier-ignore */
+                    return !style.lang || style.lang === "css"
+                        ? style.content
+                        : loadCss(i, style.lang);
+                });
+                const css = (await Promise.all(stylesheets))
+                    .filter((stylesheet) => !!stylesheet)
+                    .map((stylesheet) => `<style>${stylesheet}</style>`)
+                    .join("\n");
+                return `export default ${JSON.stringify(await highlightAndFormatCode(path, sourceWithoutStyles + css))};`;
+            }
+        },
+    };
+};

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

@@ -1,16 +1,11 @@
 import { type MarkdownSfcBlocks } from "@mdit-vue/plugin-sfc";
 import type { PluginSimple } from "markdown-it";
 import type { Plugin } from "vite";
-import type MarkdownIt from "markdown-it";
 export interface MarkdownPluginOptions {
     /**
      * Additional markdown-it setup.
      */
     markdownSetup?: PluginSimple;
-    /**
-     * The highlight option for `markdown-it`.
-     */
-    markdownHighlight?: (md: MarkdownIt, code: string, lang: string, attrs: string) => string;
 }
 export interface MarkdownItEnv {
     /**

package/dist/docs/plugins/markdown.js

@@ -3,6 +3,7 @@ import { sfcPlugin } from "@mdit-vue/plugin-sfc";
 import { frontmatterPlugin } from "@mdit-vue/plugin-frontmatter";
 import attrsPlugin from "markdown-it-attrs";
 import markdown from "markdown-it";
+import { highlightCode } from "./highlight.js";
 /**
  * Processes blocks with the lang set to `md` into HTML,
  * and turns `.md` files into single file vue components
@@ -11,8 +12,8 @@ import markdown from "markdown-it";
 export default (options) => {
     const md = markdown({
         html: true,
-        highlight(code, lang, attrs) {
-            return options?.markdownHighlight?.(md, code, lang, attrs) ?? "";
+        highlight(code, lang) {
+            return highlightCode(code, lang);
         },
     });
     md.use(frontmatterPlugin);

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

@@ -1,14 +1,15 @@
 import type { Plugin } from "vite";
 import type { App, Component } from "vue";
 import type { Router } from "vue-router";
+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>;
     /**
@@ -16,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>;
     /**
@@ -24,9 +25,33 @@ 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>;
+    /**
+     * 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;
+    };
+}
+export interface ResolvedOptions extends Omit<Options, "highlighter"> {
+    highlighter: {
+        themes: (ThemeInput | StringLiteralUnion<BundledTheme, string>)[];
+        themesInput: Record<string, string>;
+        defaultTheme: string;
+        transformers: ShikiTransformer[];
+        postprocess?: (pre: HTMLPreElement) => void;
+    };
 }
 /**
  * Add ability to access options (`docs/do11y/do11y.ts`)

package/dist/docs/plugins/plugins.js

@@ -1,5 +1,6 @@
 import ui from "./ui.js";
 import sandbox from "./sandbox.js";
+import highlight from "./highlight.js";
 import meta from "./meta/meta.js";
 import markdown from "./markdown.js";
 import block from "v-custom-block";
@@ -9,6 +10,7 @@ import { do11yOptions } from "../options.js";
 export const plugins = () => [
     ui(),
     sandbox(),
+    highlight(),
     meta(),
     markdown(do11yOptions),
     block("docs"),

package/dist/docs/plugins/sandbox.js

@@ -1,7 +1,5 @@
 import { join, parse } from "node:path";
-import { readFileSync } from "node:fs";
 import { globSync } from "tinyglobby";
-import { parse as parseVue } from "vue/compiler-sfc";
 import { root, ui } from "../files.js";
 import { indexHtml } from "../html/plugin.js";
 const toParamId = (path) => parse(path).name.toLowerCase().replace(".sandbox", "");
@@ -37,40 +35,21 @@ export default () => {
                 return `export default [${stringifiedSandboxes.join(",\n")}];`;
             }
         },
-        async transform(_, id) {
+        transform(_, id) {
             if (id.endsWith(".sandbox.vue")) {
-                const source = readFileSync(id, "utf-8");
-                const sourceWithoutStyles = source.replace(/\n<style\b[^>]*>[\s\S]*?<\/style>/gi, "");
-                const { descriptor } = parseVue(source, {
-                    filename: id,
-                    ignoreEmpty: true,
-                });
-                const usesSass = descriptor.styles.some((s) => s.lang && ["sass", "scss"].includes(s.lang));
-                const imports = descriptor.styles
-                    .map((_, i) => `import Css${i} from "${id}?vue&type=style&index=${i}&lang.scss?inline";`)
-                    .join("");
-                const stylesheets = descriptor.styles.map((_, i) => `Css${i}`).join(", ");
                 const code = `
           import { defineComponent, h } from "vue";
 
           import SandboxIframe from "${join(ui, "sandbox-iframe.js")}";
 
-          ${imports}
-
-          const sourceWithoutStyleTags = ${JSON.stringify(sourceWithoutStyles)};
-
-          const cssStylesheet = [${stylesheets}].join("");
-
-          const sourceWithStylesheet = !!cssStylesheet
-            ? sourceWithoutStyleTags + '<style>' + cssStylesheet + '</style>'
-            : sourceWithoutStyleTags;
+          import highlightedSource from "${id}?highlight";
+          import highlightedCssSource from "${id}?highlight&lang=css";
           
           export default defineComponent((props) => {
             return () => h(SandboxIframe, {
               id: "${toParamId(id)}",
-              source: ${JSON.stringify(source)},
-              sourceWithCompiledCss: ${usesSass ? "sourceWithStylesheet" : "undefined"},
-              passedProps: props,
+              highlightedSource,
+              highlightedCssSource,
             });
           });
         `.trim();

package/dist/docs/vite-config.js

@@ -39,7 +39,7 @@ const getUserPlugins = async (userViteConfig) => {
         VuePlugin({
             ...vuePluginApi.options,
             include: [/\.vue$/, /\.md$/],
-            exclude: [/\.vue\?meta$/],
+            exclude: [/\.vue\?meta$/, /\.vue\?highlight$/, /\.vue\?highlight&lang=css$/],
         }),
         ...resolvedUserPlugins.filter((i) => i.name !== "vite:vue"),
     ];

package/dist/ui/index.js

@@ -1 +1 @@
-import{createApp as e,createBlock as t,createCommentVNode as n,defineComponent as r,onBeforeMount as i,openBlock as a,renderSlot as o,shallowRef as s,unref as c,withCtx as l}from"vue";import u from"do11y:options";import{createRouter as d,createWebHistory as f}from"vue-router";import p from"do11y:routes";var m=r({__name:`Page`,setup(e){let n=s();return i(async()=>{n.value=(await u.Layout?.())?.default}),(e,r)=>n.value?(a(),t(c(n),{key:0},{default:l(()=>[o(e.$slots,`default`)]),_:3})):o(e.$slots,`default`,{key:1})}});(async()=>{let t=d({history:f(`/`),routes:p}),n=e(m);await u.setup?.(n,t),n.use(t),n.mount(`#app`)})();
+import{createApp as e,createBlock as t,createCommentVNode as n,defineComponent as r,onBeforeMount as i,openBlock as a,renderSlot as o,shallowRef as s,unref as c,withCtx as l}from"vue";import u from"do11y:options";import{createRouter as d,createWebHistory as f}from"vue-router";import p from"do11y:routes";import"do11y:css";var m=r({__name:`Page`,setup(e){let n=s();return i(async()=>{n.value=(await u.Layout?.())?.default}),(e,r)=>n.value?(a(),t(c(n),{key:0},{default:l(()=>[o(e.$slots,`default`)]),_:3})):o(e.$slots,`default`,{key:1})}});(async()=>{let t=d({history:f(`/`),routes:p}),n=e(m);await u.setup?.(n,t),n.use(t),n.mount(`#app`)})();

package/dist/ui/sandbox-iframe.js

@@ -1 +1 @@
-import{computed as e,createBlock as t,createCommentVNode as n,createElementBlock as r,defineComponent as i,mergeProps as a,onBeforeMount as o,openBlock as s,shallowRef as c,unref as l}from"vue";import u from"do11y:options";var d=[`src`],f=i({__name:`SandboxIframe`,props:{id:{},url:{},source:{},sourceWithCompiledCss:{},passedProps:{}},setup(n){let i=n,f=e(()=>`/sandbox?id=${i.id}`),p=c();return o(async()=>{p.value=(await u.SandboxIframe?.())?.default}),(e,i)=>p.value?(s(),t(l(p),a({key:0,id:n.id,url:f.value,source:n.source,"source-with-compiled-css":n.sourceWithCompiledCss},n.passedProps),null,16,[`id`,`url`,`source`,`source-with-compiled-css`])):(s(),r(`iframe`,{key:1,src:f.value},null,8,d))}});export{f as default};
+import{computed as e,createBlock as t,createCommentVNode as n,createElementBlock as r,defineComponent as i,mergeProps as a,onBeforeMount as o,openBlock as s,shallowRef as c,unref as l}from"vue";import u from"do11y:options";var d=[`src`],f=i({__name:`SandboxIframe`,props:{id:{},url:{},highlightedSource:{},highlightedCssSource:{},passedProps:{}},setup(n){let i=n,f=e(()=>`/sandbox?id=${i.id}`),p=c();return o(async()=>{p.value=(await u.SandboxIframe?.())?.default}),(e,i)=>p.value?(s(),t(l(p),a({key:0,id:n.id,url:f.value,"highlighted-source":n.highlightedSource,"highlighted-css-source":n.highlightedCssSource},n.passedProps),null,16,[`id`,`url`,`highlighted-source`,`highlighted-css-source`])):(s(),r(`iframe`,{key:1,src:f.value},null,8,d))}});export{f as default};

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "do11y",
-  "version": "0.1.2",
+  "version": "0.2.3",
   "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",
@@ -21,11 +29,16 @@
     "@mdit-vue/plugin-component": "^3.0.2",
     "@mdit-vue/plugin-frontmatter": "^3.0.2",
     "@mdit-vue/plugin-sfc": "^3.0.2",
+    "@shikijs/engine-oniguruma": "^3.22.0",
+    "@shikijs/langs": "^3.22.0",
+    "@shikijs/themes": "^3.22.0",
+    "@shikijs/transformers": "^3.22.0",
     "front-matter": "^4.0.2",
     "jsdom": "^28.1.0",
     "markdown-it": "^14.1.1",
     "markdown-it-attrs": "^4.3.1",
     "sass": "^1.97.3",
+    "shiki": "^3.22.0",
     "tinyglobby": "^0.2.15",
     "v-custom-block": "^1.0.67",
     "vue-component-meta": "^3.2.4"

package/src/types.d.ts

@@ -25,6 +25,12 @@ declare module "do11y:options" {
   export default options;
 }
 
+declare module "do11y:css" {
+  /**
+   * The CSS required for dual themes.
+   */
+}
+
 declare module "do11y:sandbox" {
   import type { Component } from "vue";