do11y 0.1.2 → 0.2.2

package/README.md

@@ -4,5 +4,7 @@ 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`.

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,32 @@
 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: {
+            themes: options.highlighter?.themes ?? [],
+            themesInput,
+            defaultTheme: options.highlighter?.defaultTheme || resolvedThemes[0],
+        },
+    };
+};
 /**
- * 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,90 @@
+import { readFileSync } from "node:fs";
+import { parse as parseVue } from "vue/compiler-sfc";
+import { format } from "oxfmt";
+import { createHighlighter, bundledLanguages, bundledThemes } from "shiki";
+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(),
+        ],
+    });
+};
+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,
+          [data-theme="${theme}"] .shiki span {
+            background-color: var(--shiki-${theme}-bg) !important;
+            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,6 +1,7 @@
 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 { MarkdownPluginOptions } from "./markdown.js";
 export interface Options extends MarkdownPluginOptions {
     /**
@@ -27,6 +28,26 @@ export interface Options extends MarkdownPluginOptions {
      * Custom wrapper component for `?iframe` 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>;
+    };
+}
+export interface ResolvedOptions extends Omit<Options, "highlighter"> {
+    highlighter: {
+        themes: (ThemeInput | StringLiteralUnion<BundledTheme, string>)[];
+        themesInput: Record<string, string>;
+        defaultTheme: string;
+    };
 }
 /**
  * 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,6 +1,6 @@
 {
   "name": "do11y",
-  "version": "0.1.2",
+  "version": "0.2.2",
   "description": "A bare-bones tool to document Vue components.",
   "license": "MIT",
   "repository": "github:sq11y/do11y",
@@ -21,11 +21,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";