@do11y/docs 0.0.2 → 0.0.4

package/README.md

@@ -0,0 +1,125 @@
+# @do11y/docs
+
+A very bare-bones tool to help document Vue components.
+
+- Write documentation in Markdown files that get treated as Vue components
+- Import markdown files with a `title` and `slug` added through frontmatter as routes
+- Sandbox components - e.g. `Button.sandbox.vue` will be available on the url `/sandbox?id=button`
+
+## Install
+
+```bash
+npm i @do11y/docs
+```
+
+## Setup
+
+### Allow markdown files in `vite.config.ts` file
+
+```ts
+import { fileURLToPath, URL } from 'node:url';
+
+import { defineConfig } from 'vite';
+
+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)),
+    },
+  },
+});
+```
+
+### Add scripts to `package.json`
+
+```json
+{
+  "scripts": {
+    "docs:dev": "do11y",
+    "docs:build": "do11y build",
+    "docs:preview": "do11y preview"
+  }
+}
+```
+
+### Add the `docs` folder
+
+#### Add `tsconfig.json` file
+
+```json
+{
+  "extends": "../tsconfig.json",
+  "include": ["site/**/*", "../src/**/*"],
+
+  "compilerOptions": {
+    "types": ["@do11y/docs/types"]
+  }
+}
+```
+
+#### Add a `site/index.ts` file
+
+This file will be used to configure the documentation site. The configuration requires you to pass an import for the main `Site` component.
+
+> [!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.
+
+```ts
+import type { Site } from '@do11y/docs';
+
+export default {
+  Site: () => import('./Site.vue'),
+
+  setup(app) {
+    // App setup
+  },
+} satisfies Site;
+```
+
+#### Add a `site/plugins.ts` file
+
+This file will be used to configure the different plugins available.
+
+```ts
+import type { PluginOptions } from '@do11y/docs';
+
+export default {
+  metaRenderer(meta, title) {
+    return `
+      <h3>${title}</h3>
+      <pre><code>${JSON.stringify(meta, null, 2)}</code></pre>
+    `;
+  },
+} satisfies PluginOptions;
+```
+
+#### Add a main `Site` component
+
+Inside the app you can import the available routes from `dolly:routes`.
+
+```vue
+<template>
+  <nav>
+    <ul>
+      <template v-for="route of routes" :key="route.path">
+        <li>
+          <router-link :to="route.path">
+            {{ route.meta.title }}
+          </router-link>
+        </li>
+      </template>
+    </ul>
+  </nav>
+
+  <RouterView />
+</template>
+
+<script lang="ts" setup>
+  import routes from 'do11y:routes';
+</script>
+```

package/dist/cli.d.ts

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

package/dist/files.d.ts

@@ -0,0 +1,4 @@
+export declare const ui: string;
+export declare const root: string;
+export declare const docs: string;
+export declare const plugins: string;

package/dist/html/html.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from 'vite';
+export declare const html: (folder: string, key: "index" | "sandbox") => Omit<Plugin, "name">;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { PluginOptions } from './plugin-options.js';
+import type { Site } from './plugins/site/site.js';
+export type { Site, PluginOptions };

package/dist/plugin-options.d.ts

@@ -0,0 +1,6 @@
+import type { MarkdownPluginOptions } from './plugins/markdown/markdown.js';
+export type PluginOptions = MarkdownPluginOptions;
+/**
+ * Access plugin options (`docs/site/plugins.ts`).
+ */
+export declare const pluginOptions: PluginOptions;

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

@@ -0,0 +1,36 @@
+import { type MarkdownSfcBlocks } from '@mdit-vue/plugin-sfc';
+import type { PluginOptions, MarkdownItEnv as Env } from 'markdown-it-vue-meta';
+import type { PluginSimple } from 'markdown-it';
+import type { Plugin } from 'vite';
+import type MarkdownIt from 'markdown-it';
+export interface MarkdownPluginOptions {
+    /**
+     * Additional markdown-it setup.
+     */
+    setup?: PluginSimple;
+    /**
+     * The highlight option for `markdown-it`.
+     */
+    highlight?: (md: MarkdownIt, code: string, lang: string, attrs: string) => string;
+    /**
+     * The renderer option for `markdown-it-vue-meta`.
+     */
+    metaRenderer?: PluginOptions['renderer'];
+}
+export interface MarkdownItEnv extends Env {
+    /**
+     * Blocks extracted by `@mdit-vue/plugin-sfc`.
+     */
+    sfcBlocks?: MarkdownSfcBlocks;
+    /**
+     * Blocks extracted by `@mdit-vue/plugin-frontmatter`.
+     */
+    frontmatter?: Record<string, unknown>;
+}
+/**
+ * Processes blocks with the lang set to `md` into HTML,
+ * and turns `.md` files into single file vue components
+ * - using `markdown-it`.
+ */
+declare const _default: (options?: MarkdownPluginOptions) => Plugin;
+export default _default;

package/dist/plugins/plugins.d.ts

@@ -0,0 +1,2 @@
+import type { Plugin } from 'vite';
+export declare const plugins: () => Plugin[];

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

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

package/dist/plugins/sandbox/sandbox.d.ts

@@ -0,0 +1,8 @@
+import type { Plugin } from 'vite';
+/**
+ * Creates a seprate sandbox app, and
+ * adds the ability to declare sandbox components
+ * which you can access through `do11y:sandbox`.
+ */
+declare const _default: () => Plugin;
+export default _default;

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

@@ -0,0 +1,19 @@
+import type { Plugin } from 'vite';
+import type { App, Component } from 'vue';
+import type { Router } from 'vue-router';
+export type Site = {
+    /**
+     * The main component for the site.
+     */
+    Site: () => Promise<Component>;
+    /**
+     * Additional setup for the app.
+     */
+    setup?(app: App, router: Router): void | Promise<void>;
+};
+/**
+ * Add ability to access the site options (`docs/site/index.ts`)
+ * through `do11y:site`.
+ */
+declare const _default: () => Plugin;
+export default _default;

package/dist/plugins/ui/ui.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from 'vite';
+/**
+ * The main application.
+ */
+declare const _default: () => Plugin;
+export default _default;

package/dist/vite-config.d.ts

@@ -0,0 +1,2 @@
+export declare const getUserViteConfig: (command: "dev" | "build" | "preview") => Promise<import("vite").UserConfig>;
+export declare const getViteConfig: (command: "dev" | "build" | "preview") => Promise<Record<string, any>>;

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@do11y/docs",
-  "version": "0.0.2",
+  "description": "A very bare-bones tool to help document Vue components.",
+  "version": "0.0.4",
   "type": "module",
   "repository": {
     "type": "git",
@@ -15,7 +16,10 @@
     "do11y": "./bin/bin.js"
   },
   "exports": {
-    ".": "./dist/index.js",
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
     "./types": "./routes.d.ts"
   },
   "peerDependencies": {
@@ -35,7 +39,7 @@
     "markdown-it-mark": "^4.0.0",
     "markdown-it-vue-meta": "^0.0.2",
     "v-custom-block": "^1.0.67",
-    "@do11y/ui": "0.0.1"
+    "@do11y/ui": "0.0.2"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.3",