@do11y/docs 0.0.12 → 0.0.14

package/README.md

@@ -5,6 +5,7 @@ A very bare-bones tool to help document Vue components.
 - Write documentation in Markdown files that get treated as Vue components.
 - Import markdown files as routes.
 - Add sandbox components - e.g. `Button.sandbox.vue` will be available on the url `/sandbox?id=button`.
+- Easily document components with [vue-component-meta](https://www.npmjs.com/package/vue-component-meta) using meta imports - e.g. `Button.vue?meta`.
 
 ## Setup
 
@@ -14,18 +15,12 @@ A very bare-bones tool to help document Vue components.
 import { fileURLToPath, URL } from 'node:url';
 
 import { defineConfig } from 'vite';
+import { vueOptions } from '@do11y/docs';
 
 import vue from '@vitejs/plugin-vue';
-import vueDevTools from 'vite-plugin-vue-devtools';
 
 export default defineConfig({
-  plugins: [vue({ include: [/\.vue$/, /\.md$/] }), vueDevTools()],
-
-  resolve: {
-    alias: {
-      '@': fileURLToPath(new URL('./src', import.meta.url)),
-    },
-  },
+  plugins: [vue(vueOptions)],
 });
 ```
 
@@ -38,7 +33,7 @@ The scaffold makes the assumption that you have a `src` folder and a `tsconfig.j
 npm i @do11y/docs
 
 // Scaffold the `docs` folder
-npm do11y-scaffold
+npm do11y scaffold
 ```
 
 ### Add scripts to `package.json`
@@ -64,19 +59,24 @@ npm docs:dev
 
 ### `site/index.ts`
 
-This file will be used to configure the documentation site.
+This file will be used to configure the site.
 
 > [!WARNING]
-> Both the documentation site and the sandbox uses the same `setup` function. This means importing styles or components directly in this file will also import them to the sandbox.
+> Both the documentation site and the sandbox import this file - this is why it is recommended to import necessary files/components _inside_ the functions.
 
 ```ts
 import type { Site } from '@do11y/docs';
 
 export default {
+  // The main component for the site.
   Site: () => import('./Site.vue'),
 
-  setup(app) {
-    // App setup
+  async setup(app, router) {
+    // Additional setup for the app.
+  },
+
+  async setupSandbox(app) {
+    // Additional setup for the sandbox app.
   },
 } satisfies Site;
 ```
@@ -89,11 +89,12 @@ This file will be used to configure the different plugins available.
 import type { PluginOptions } from '@do11y/docs';
 
 export default {
-  metaRenderer(meta, title) {
-    return `
-      <h3>${title}</h3>
-      <pre><code>${JSON.stringify(meta, null, 2)}</code></pre>
-    `;
-  },
+  setup(md) {
+    // Additional markdown-it setup.
+  }
+
+  highlight(md, code, lang, attrs) {
+    // The highlight option for `markdown-it`.
+  }
 } satisfies PluginOptions;
 ```

package/dist/cli.js

@@ -1,17 +1,25 @@
+import { cp } from 'node:fs/promises';
+import { join } from 'node:path';
 import { createServer, build, preview } from 'vite';
 import { getViteConfig } from './vite-config.js';
+import { docs } from './files.js';
 const [_, __, command = 'dev'] = process.argv;
-if (command !== 'dev' && command !== 'build' && command !== 'preview') {
+if (command !== 'scaffold' && command !== 'dev' && command !== 'build' && command !== 'preview') {
     throw new Error();
 }
-const viteConfig = await getViteConfig(command);
-if (command === 'dev') {
+if (command === 'scaffold') {
+    const template = join(import.meta.dirname, '../template');
+    await cp(template, docs, { recursive: true });
+}
+else if (command === 'dev') {
+    const viteConfig = await getViteConfig(command);
     const server = await createServer(viteConfig);
     await server.listen();
     server.printUrls();
     server.bindCLIShortcuts({ print: true });
 }
 else {
+    const viteConfig = await getViteConfig(command);
     await build(viteConfig);
     if (command === 'preview') {
         const previewServer = await preview(viteConfig);

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import type { PluginOptions } from './plugin-options.js';
 import type { Site } from './plugins/site/site.js';
-export type { Site, PluginOptions };
+import type { Meta } from './plugins/meta/meta-types.js';
+export type { PluginOptions, Site, Meta };
 export declare const vueOptions: {
     include: RegExp[];
     exclude: RegExp[];

package/dist/plugin-options.d.ts

@@ -3,4 +3,4 @@ export type PluginOptions = MarkdownPluginOptions;
 /**
  * Access plugin options (`docs/site/plugins.ts`).
  */
-export declare const pluginOptions: PluginOptions;
+export declare const pluginOptions: PluginOptions | undefined;

package/dist/plugin-options.js

@@ -1,5 +1,8 @@
+import { existsSync } from 'node:fs';
 import { plugins } from './files.js';
 /**
  * Access plugin options (`docs/site/plugins.ts`).
  */
-export const pluginOptions = (await import(plugins)).default;
+export const pluginOptions = existsSync(plugins)
+    ? (await import(plugins)).default
+    : undefined;

package/dist/plugins/meta/meta-mapper.d.ts

@@ -1,42 +1,3 @@
 import type { ComponentMeta } from 'vue-component-meta';
-export declare const mapMeta: (meta: ComponentMeta, render: (input: string) => string) => {
-    modelValues: {
-        default: string | undefined;
-        required: boolean;
-        name: string;
-        type: string;
-        description: string;
-        deprecated: string | boolean;
-        tags: {
-            name: string;
-            text: string | undefined;
-        }[];
-    }[];
-    props: {
-        default: string | undefined;
-        required: boolean;
-        name: string;
-        type: string;
-        description: string;
-        deprecated: string | boolean;
-        tags: {
-            name: string;
-            text: string | undefined;
-        }[];
-    }[];
-    events: {
-        name: string;
-        type: string;
-        description: string;
-        deprecated: string | boolean;
-        tags: {
-            name: string;
-            text: string | undefined;
-        }[];
-    }[];
-    slots: {
-        name: string;
-        type: string;
-        description: string;
-    }[];
-};
+import type { Meta } from './meta-types';
+export declare const mapMeta: (meta: ComponentMeta, render: (input: string) => string) => Meta;

package/dist/plugins/meta/meta-mapper.js

@@ -17,20 +17,20 @@ export const mapMeta = (meta, render) => {
             text: tag.text ? render(tag.text) : undefined,
         }));
     };
-    const mapPropertyAndEvent = (prop) => ({
+    const mapEvent = (prop) => ({
         name: prop.name,
         type: prop.type,
-        description: render(prop.description),
+        description: prop.description ? render(prop.description) : undefined,
         deprecated: getDeprecated(prop.tags),
         tags: getFilteredTags(prop.tags),
     });
-    const mapSlotAndExposed = (m) => ({
-        name: m.name,
-        type: m.type,
-        description: render(m.description),
+    const mapSlotAndExposed = (se) => ({
+        name: se.name,
+        type: se.type,
+        description: se.description ? render(se.description) : undefined,
     });
     const mapProperty = (prop) => ({
-        ...mapPropertyAndEvent(prop),
+        ...mapEvent(prop),
         default: prop.default || getTag(prop.tags, 'default')?.text,
         required: prop.required,
     });
@@ -43,7 +43,7 @@ export const mapMeta = (meta, render) => {
             .map((prop) => mapProperty(prop)),
         events: meta.events
             .filter((event) => !hasAssociatedProp(event))
-            .map((event) => mapPropertyAndEvent(event)),
+            .map((event) => mapEvent(event)),
         slots: meta.slots.map((slot) => mapSlotAndExposed(slot)),
     };
 };

package/dist/plugins/meta/meta-types.d.ts

@@ -0,0 +1,22 @@
+import { PropertyMeta } from 'vue-component-meta';
+interface Property {
+    name: string;
+    type: string;
+    description?: string;
+    deprecated: string | boolean;
+    tags: PropertyMeta['tags'][number][];
+    default?: string;
+    required: boolean;
+}
+interface SlotOrExposed {
+    name: string;
+    type: string;
+    description?: string;
+}
+export interface Meta {
+    modelValues: Property[];
+    props: Property[];
+    events: Omit<Property, 'default' | 'required'>[];
+    slots: SlotOrExposed[];
+}
+export {};

package/dist/plugins/meta/meta-types.js

@@ -0,0 +1 @@
+export {};

package/dist/plugins/routes/routes.d.ts

@@ -1,7 +1,7 @@
 import type { Plugin } from 'vite';
 /**
- * Adds the ability to import routes (`*.md` files)
- * through `do11y:routes`.
+ * Adds the ability to import routes (`*.md` files with
+ * a `title` and `slug`) through `do11y:routes`.
  */
 declare const _default: () => Plugin;
 export default _default;

package/dist/plugins/routes/routes.js

@@ -3,8 +3,8 @@ import fg from 'fast-glob';
 import fm from 'front-matter';
 import { root } from '../../files.js';
 /**
- * Adds the ability to import routes (`*.md` files)
- * through `do11y:routes`.
+ * Adds the ability to import routes (`*.md` files with
+ * a `title` and `slug`) through `do11y:routes`.
  */
 export default () => {
     const moduleId = 'do11y:routes';

package/dist/plugins/site/site.d.ts

@@ -3,13 +3,17 @@ import type { App, Component } from 'vue';
 import type { Router } from 'vue-router';
 export interface Site {
     /**
-     * The main component for the site.
+     * The wrapper component for the site.
      */
     Site: () => Promise<Component>;
     /**
      * Additional setup for the app.
      */
     setup?(app: App, router: Router): void | Promise<void>;
+    /**
+     * The wrapper component for the sandbox.
+     */
+    Sandbox?: () => Promise<Component>;
     /**
      * Additional setup for the sandbox app.
      */

package/dist/scaffold.js

@@ -1,5 +1,4 @@
-import { cp } from 'fs/promises';
-import { join } from 'path';
-import { searchForWorkspaceRoot } from 'vite';
-const target = join(searchForWorkspaceRoot(process.cwd()), 'docs');
-await cp(join(import.meta.dirname, '../template'), target, { recursive: true });
+import { cp } from 'node:fs/promises';
+import { join } from 'node:path';
+import { docs } from './files.js';
+await cp(join(import.meta.dirname, '../template'), docs, { recursive: true });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@do11y/docs",
   "description": "A very bare-bones tool to help document Vue components.",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "type": "module",
   "repository": {
     "type": "git",
@@ -11,18 +11,17 @@
     "bin",
     "dist",
     "template",
-    "routes.d.ts"
+    "types.d.ts"
   ],
   "bin": {
-    "do11y": "./bin/cli.js",
-    "do11y-scaffold": "./bin/scaffold.js"
+    "do11y": "./bin/cli.js"
   },
   "exports": {
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
-    "./types": "./routes.d.ts"
+    "./types": "./types.d.ts"
   },
   "peerDependencies": {
     "@vitejs/plugin-vue": "^6.0.2",
@@ -40,7 +39,7 @@
     "markdown-it-attrs": "^4.3.1",
     "v-custom-block": "^1.0.67",
     "vue-component-meta": "^3.1.8",
-    "@do11y/ui": "0.0.6"
+    "@do11y/ui": "0.0.7"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.3",

package/template/site/Sandbox.vue

@@ -0,0 +1,20 @@
+<template>
+  <main>
+    <slot />
+  </main>
+</template>
+
+<style>
+  html {
+    height: 100%;
+  }
+
+  body {
+    margin: 0;
+    height: 100%;
+
+    display: grid;
+    place-content: center;
+    background-color: #eee;
+  }
+</style>

package/template/site/SandboxIframe.vue

@@ -24,9 +24,13 @@
   const url = computed(() => `${window.location.origin}/sandbox?id=${props.id}`);
 </script>
 
-<style>
+<style scoped>
   iframe {
     border: none;
     width: 100%;
   }
+
+  a {
+    float: right;
+  }
 </style>

package/template/site/Site.vue

@@ -10,7 +10,9 @@
   </nav>
 
   <main>
-    <RouterView />
+    <article>
+      <RouterView />
+    </article>
   </main>
 </template>
 

package/template/site/index.ts

@@ -2,8 +2,9 @@ import type { Site } from '@do11y/docs';
 
 export default {
   Site: () => import('./Site.vue'),
+  Sandbox: () => import('./Sandbox.vue'),
 
-  async setup(app) {
+  async setup(app, router) {
     const SandboxIframe = (await import('./SandboxIframe.vue')).default;
     app.component('SandboxIframe', SandboxIframe);
   },

package/template/site/style.css

@@ -1,6 +1,8 @@
 html {
   scrollbar-gutter: stable;
   scrollbar-width: thin;
+
+  font-family: sans-serif;
 }
 
 *,
@@ -15,7 +17,6 @@ html {
   margin: 0;
 }
 
-[id],
 :target {
   scroll-margin-block: 2em;
 }
@@ -36,6 +37,49 @@ pre {
 }
 
 body {
-  margin-inline: auto;
-  inline-size: min(90dvw, 50rem);
+  margin: 2rem auto;
+  inline-size: min(90dvw, 40rem);
+}
+
+nav ul {
+  display: flex;
+  align-items: center;
+  gap: 2rem;
+
+  margin-block-end: 2rem;
+  margin-inline-start: 1rem;
+}
+
+pre {
+  border-radius: 4px;
+  padding: 1rem;
+
+  background-color: #1a1a1a;
+  color: #fff;
+}
+
+/* Heading directly after another heading */
+:is(h1, h2, h3, h4, h5, h6) + :is(h1, h2, h3, h4, h5, h6) {
+  margin-block-start: 1.5rem;
+}
+
+/* Heading directly after content */
+:not(h1, h2, h3, h4, h5, h6) + :is(h1, h2, h3, h4, h5, h6) {
+  margin-block-start: 2em;
+}
+
+/* Content directly after a heading */
+:is(h1, h2, h3, h4, h5, h6) + :not(h1, h2, h3, h4, h5, h6) {
+  margin-block-start: 1.5em;
+}
+
+/* Content directly after content */
+:is(article > div, iframe, p, small, blockquote, table, dl, pre, ol, ul, br)
+  + :is(article > div, iframe, small, blockquote, table, dl, pre, ol, ul, br) {
+  margin-block-start: 1em;
+}
+
+button {
+  background-color: transparent;
+  border: 1px solid #1a1a1a;
 }

package/template/tsconfig.json

@@ -3,6 +3,7 @@
   "include": ["site/**/*", "../src/**/*"],
 
   "compilerOptions": {
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
     "types": ["@do11y/docs/types"]
   }
 }

package/types.d.ts

@@ -0,0 +1,12 @@
+declare module 'do11y:routes' {
+  import type { RouteRecordRaw as VueRouteRecordRaw } from 'vue-router';
+  type RouteRecordRaw = Omit<VueRouteRecordRaw, 'meta'> & { meta: { title: string; slug: string } };
+  const routes: RouteRecordRaw[];
+  export default routes;
+}
+
+declare module '*.vue?meta' {
+  import type { Meta } from '@do11y/docs';
+  const meta: Meta;
+  export default meta;
+}

package/bin/scaffold.js

@@ -1,4 +0,0 @@
-#!/usr/bin/env node
-'use strict';
-
-import '../dist/scaffold.js';

package/routes.d.ts

@@ -1,5 +0,0 @@
-declare module 'do11y:routes' {
-  import type { RouteRecordRaw } from 'vue-router';
-  const routes: (Omit<RouteRecordRaw, 'meta'> & { meta: { title: string; slug: string } })[];
-  export default routes;
-}

package/template/site/plugins.ts

@@ -1,3 +0,0 @@
-import type { PluginOptions } from '@do11y/docs';
-
-export default {} satisfies PluginOptions;