@do11y/docs 0.0.6 → 0.0.8

package/README.md

@@ -2,15 +2,9 @@
 
 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
-```
+- 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`.
 
 ## Setup
 
@@ -35,6 +29,18 @@ export default defineConfig({
 });
 ```
 
+### Initiate and scaffold
+
+The scaffold makes the assumption that you have a `src` folder and a `tsconfig.json` file it can extend.
+
+```sh
+// Install
+npm i @do11y/docs
+
+// Scaffold the `docs` folder
+npm do11y-scaffold
+```
+
 ### Add scripts to `package.json`
 
 ```json
@@ -47,24 +53,18 @@ export default defineConfig({
 }
 ```
 
-### Add the `docs` folder
+### Run the dev environment
 
-#### Add `tsconfig.json` file
-
-```json
-{
-  "extends": "../tsconfig.json",
-  "include": ["site/**/*", "../src/**/*"],
-
-  "compilerOptions": {
-    "types": ["@do11y/docs/types"]
-  }
-}
+```sh
+// Install
+npm docs:dev
 ```
 
-#### Add a `site/index.ts` file
+## Files
+
+### `site/index.ts`
 
-This file will be used to configure the documentation site. The configuration requires you to pass an import for the main `Site` component.
+This file will be used to configure the documentation 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.
@@ -81,7 +81,7 @@ export default {
 } satisfies Site;
 ```
 
-#### Add a `site/plugins.ts` file
+### `site/plugins.ts`
 
 This file will be used to configure the different plugins available.
 
@@ -97,29 +97,3 @@ export default {
   },
 } 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/bin/scaffold.js

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

package/dist/scaffold.d.ts

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

package/dist/scaffold.js

@@ -0,0 +1,5 @@
+import { cp } from 'fs/promises';
+import { join } from 'path';
+import { searchForWorkspaceRoot } from 'vite';
+const target = join(searchForWorkspaceRoot(process.cwd()), 'example', 'docs');
+await cp(join(import.meta.dirname, '../template'), target, { 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.6",
+  "version": "0.0.8",
   "type": "module",
   "repository": {
     "type": "git",
@@ -10,10 +10,12 @@
   "files": [
     "bin",
     "dist",
+    "template",
     "routes.d.ts"
   ],
   "bin": {
-    "do11y": "./bin/bin.js"
+    "do11y": "./bin/cli.js",
+    "do11y-scaffold": "./bin/scaffold.js"
   },
   "exports": {
     ".": {
@@ -40,7 +42,7 @@
     "markdown-it-mark": "^4.0.0",
     "markdown-it-vue-meta": "^0.0.2",
     "v-custom-block": "^1.0.67",
-    "@do11y/ui": "0.0.4"
+    "@do11y/ui": "0.0.5"
   },
   "devDependencies": {
     "@tsconfig/node24": "^24.0.3",

package/template/Example.md

@@ -0,0 +1,17 @@
+---
+title: 'Example'
+slug: '/example'
+---
+
+<script setup>
+  import { useRoute } from 'vue-router';
+
+  const route = useRoute();
+</script>
+
+# {{ route.meta.title }}
+
+Lorem ipsum dolor sit amet consectetur adipisicing elit. Asperiores, harum itaque consequatur vel
+voluptatem vero labore aliquam fuga veritatis, voluptatum architecto. Obcaecati, vitae delectus
+aperiam deleniti quod, ducimus vero quas, adipisci molestias placeat neque? Sapiente sint nam
+tempora commodi! Adipisci iure unde alias ab quasi maxime enim porro cum vero.

package/template/site/SandboxPlayground.vue

@@ -0,0 +1,27 @@
+<template>
+  <div class="iframe-wrapper">
+    <iframe ref="iframe" :title="`Sandbox for ${title}`" :src="url" />
+  </div>
+
+  <a :href="url" target="_blank" rel="noopener noreferrer">Open in a new tab</a>
+</template>
+
+<script lang="ts" setup>
+  import { computed, ref } from 'vue';
+
+  const props = defineProps<{
+    title: string;
+    id: string;
+  }>();
+
+  const iframe = ref<HTMLIFrameElement>();
+
+  const url = computed(() => `${window.location.origin}/sandbox?id=${props.id}`);
+</script>
+
+<style scoped>
+  iframe {
+    border: none;
+    width: 100%;
+  }
+</style>

package/template/site/Site.vue

@@ -0,0 +1,26 @@
+<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';
+  import './style.css';
+</script>
+
+<style>
+  button {
+    width: max-content;
+  }
+</style>

package/template/site/index.ts

@@ -0,0 +1,10 @@
+import type { Site } from '@do11y/docs';
+
+export default {
+  Site: () => import('./Site.vue'),
+
+  async setup(app) {
+    const SandboxPlaygroundComponent = (await import('./SandboxPlayground.vue')).default;
+    app.component('SandboxPlayground', SandboxPlaygroundComponent);
+  },
+} satisfies Site;

package/template/site/plugins.ts

@@ -0,0 +1,10 @@
+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;

package/template/site/style.css

@@ -0,0 +1,77 @@
+html {
+  scrollbar-gutter: stable;
+  scrollbar-width: thin;
+}
+
+*,
+*::before,
+*::after,
+*::details-content {
+  box-sizing: border-box;
+  padding: 0;
+}
+
+*:not(dialog) {
+  margin: 0;
+}
+
+:target {
+  scroll-margin-block: 2em;
+}
+
+a,
+button {
+  cursor: pointer;
+}
+
+button {
+  color: inherit;
+}
+
+button:disabled,
+button[aria-disabled='true'] {
+  cursor: default;
+}
+
+button,
+input,
+textarea,
+select {
+  font: inherit;
+  letter-spacing: inherit;
+  word-spacing: inherit;
+}
+
+textarea {
+  field-sizing: content;
+}
+
+a {
+  text-underline-position: from-font;
+}
+
+pre {
+  white-space: pre-wrap;
+}
+
+code {
+  word-break: break-all;
+}
+
+pre,
+table,
+img,
+svg,
+picture,
+video,
+canvas,
+iframe {
+  max-inline-size: 100%;
+  min-inline-size: 0;
+
+  display: block;
+}
+
+[id] {
+  scroll-margin-top: 2rem;
+}

package/template/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.json",
+  "include": ["site/**/*", "../src/**/*"],
+
+  "compilerOptions": {
+    "types": ["@do11y/docs/types"]
+  }
+}