vitepress-theme-pm 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pierce
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# vitepress-project-management
+
+A VitePress theme that adds a kanban board for project management. Tickets are individual `.md` files with YAML frontmatter — your board lives in your docs repo.
+
+[Demo](https://mcbridemusings.github.io/vitepress-project-management/board.html)
+
+## Install
+
+```bash
+npm install vitepress-theme-pm
+```
+
+## Setup
+
+### 1. Theme
+
+`.vitepress/theme/index.ts`:
+
+```ts
+import Theme from "vitepress-theme-pm";
+export default Theme;
+```
+
+### 2. Plugin
+
+`.vitepress/config.ts`:
+
+```ts
+import { defineConfig } from "vitepress";
+import { markdownWriterPlugin } from "vitepress-theme-pm/plugin";
+
+export default defineConfig({
+  vite: {
+    plugins: [markdownWriterPlugin()],
+  },
+});
+```
+
+### 3. Board page
+
+Create `board.md` at your site root:
+
+```yaml
+---
+layout: page
+board: true
+ticketsDir: tickets
+ticketPrefix: PM
+defaultColumn: backlog
+columns:
+  - { key: backlog, label: Backlog, color: "#718096" }
+  - { key: doing, label: In Progress, color: "#e6a817" }
+  - { key: review, label: Review, color: "#9f7aea" }
+  - { key: done, label: Done, color: "#6bcb6b" }
+---
+```
+
+### 4. Create tickets
+
+Via the board UI (click **+ New**) or CLI:
+
+```bash
+npx vitepress-theme-pm ticket "Fix login bug" --status doing --priority high --tags auth,ui
+```
+
+Tickets are markdown files in `tickets/` with frontmatter for metadata and a body for description.
+
+## How it works
+
+- The board extends VitePress's default theme — all your docs pages keep their sidebar, TOC, and nav
+- Tickets are plain `.md` files with `id`, `title`, `status`, `priority`, and `tags` in frontmatter
+- Drag-and-drop between columns updates the ticket file
+- A Vite dev server plugin handles reads/writes (dev only — no server code in production builds)
+- The CLI creates ticket files from the terminal
+
+## License
+
+MIT

package/dist/plugin.mjs

@@ -0,0 +1,184 @@
+// src/plugins/markdownWriter.ts
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+function scanTickets(ticketsDir, dirRelative) {
+  if (!fs.existsSync(ticketsDir)) return [];
+  const files = fs.readdirSync(ticketsDir).filter((f) => f.endsWith(".md"));
+  return files.map((file) => {
+    const raw = fs.readFileSync(path.join(ticketsDir, file), "utf-8");
+    const parsed = matter(raw);
+    return {
+      id: Number(parsed.data.id) || 0,
+      title: parsed.data.title || path.basename(file, ".md"),
+      status: parsed.data.status || "backlog",
+      priority: parsed.data.priority || "medium",
+      tags: parsed.data.tags || [],
+      body: parsed.content.trim(),
+      url: `/${dirRelative}/${path.basename(file, ".md")}.html`
+    };
+  });
+}
+function getMaxTicketId(ticketsDir) {
+  if (!fs.existsSync(ticketsDir)) return 0;
+  const files = fs.readdirSync(ticketsDir).filter((f) => f.endsWith(".md"));
+  let max = 0;
+  for (const file of files) {
+    const raw = fs.readFileSync(path.join(ticketsDir, file), "utf-8");
+    const parsed = matter(raw);
+    const id = Number(parsed.data.id);
+    if (id > max) max = id;
+  }
+  return max;
+}
+function findMarkdownFiles(dir) {
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules") {
+      results.push(...findMarkdownFiles(full));
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+function markdownWriterPlugin() {
+  let srcDir = "";
+  let nextId = 0;
+  return {
+    name: "vitepress-pm-markdown-writer",
+    configResolved(config) {
+      srcDir = config.root;
+    },
+    configureServer(server) {
+      server.middlewares.use("/__vitepress_pm_tickets", (req, res) => {
+        const url = new URL(req.url || "/", "http://localhost");
+        const dir = url.searchParams.get("dir") || "tickets";
+        const ticketsDir = path.resolve(srcDir, dir);
+        const tickets = scanTickets(ticketsDir, dir);
+        let maxId = 0;
+        for (const t of tickets) {
+          if (t.id > maxId) maxId = t.id;
+        }
+        nextId = maxId + 1;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify(tickets));
+      });
+      server.middlewares.use("/__vitepress_pm_create", (req, res) => {
+        if (req.method !== "POST") {
+          res.statusCode = 405;
+          res.end("Method not allowed");
+          return;
+        }
+        let body = "";
+        req.on("data", (chunk) => {
+          body += chunk;
+        });
+        req.on("end", () => {
+          try {
+            const { dir, status, title, priority, tags, body: ticketBody } = JSON.parse(body);
+            const ticketsDir = path.resolve(srcDir, dir || "tickets");
+            if (!fs.existsSync(ticketsDir)) {
+              fs.mkdirSync(ticketsDir, { recursive: true });
+            }
+            const currentMax = getMaxTicketId(ticketsDir);
+            if (nextId <= currentMax) nextId = currentMax + 1;
+            const id = nextId++;
+            const frontmatter = {
+              id,
+              title: title || "New ticket",
+              status: status || "backlog",
+              priority: priority || "medium",
+              tags: tags || []
+            };
+            const bodyContent = ticketBody ? `
+${ticketBody}
+` : "\n";
+            const content = matter.stringify(bodyContent, frontmatter);
+            const filePath = path.join(ticketsDir, `${id}.md`);
+            fs.writeFileSync(filePath, content);
+            const ticket = {
+              ...frontmatter,
+              body: ticketBody || "",
+              url: `/${dir || "tickets"}/${id}.html`
+            };
+            res.setHeader("Content-Type", "application/json");
+            res.end(JSON.stringify(ticket));
+          } catch (e) {
+            res.statusCode = 500;
+            res.end(String(e));
+          }
+        });
+      });
+      server.middlewares.use("/__vitepress_pm_update", (req, res) => {
+        if (req.method !== "POST") {
+          res.statusCode = 405;
+          res.end("Method not allowed");
+          return;
+        }
+        let body = "";
+        req.on("data", (chunk) => {
+          body += chunk;
+        });
+        req.on("end", () => {
+          try {
+            const { url, updates } = JSON.parse(body);
+            if (!url || typeof url !== "string") {
+              res.statusCode = 400;
+              res.end("Missing url");
+              return;
+            }
+            const mdPath = url.replace(/\.html$/, ".md").replace(/^\//, "");
+            const filePath = path.resolve(srcDir, mdPath);
+            if (!fs.existsSync(filePath)) {
+              res.statusCode = 404;
+              res.end(`File not found: ${mdPath}`);
+              return;
+            }
+            const raw = fs.readFileSync(filePath, "utf-8");
+            const parsed = matter(raw);
+            for (const [key, value] of Object.entries(updates)) {
+              if (key === "body") {
+                parsed.content = "\n" + String(value) + "\n";
+              } else {
+                parsed.data[key] = value;
+              }
+            }
+            const output = matter.stringify(parsed.content, parsed.data);
+            fs.writeFileSync(filePath, output);
+            res.statusCode = 200;
+            res.end("ok");
+          } catch (e) {
+            res.statusCode = 500;
+            res.end(String(e));
+          }
+        });
+      });
+    },
+    generateBundle() {
+      const mdFiles = findMarkdownFiles(srcDir);
+      const seen = /* @__PURE__ */ new Set();
+      for (const file of mdFiles) {
+        const raw = fs.readFileSync(file, "utf-8");
+        const parsed = matter(raw);
+        if (!parsed.data.board) continue;
+        const dir = parsed.data.ticketsDir || "tickets";
+        if (seen.has(dir)) continue;
+        seen.add(dir);
+        const ticketsDir = path.resolve(srcDir, dir);
+        const tickets = scanTickets(ticketsDir, dir);
+        this.emitFile({
+          type: "asset",
+          fileName: `__vitepress_pm_tickets/${dir}.json`,
+          source: JSON.stringify(tickets)
+        });
+      }
+    }
+  };
+}
+export {
+  getMaxTicketId,
+  markdownWriterPlugin,
+  scanTickets
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "vitepress-theme-pm",
+  "version": "0.1.0",
+  "description": "A VitePress theme that adds a kanban board for project management with markdown tickets",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/McBrideMusings/vitepress-project-management",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/McBrideMusings/vitepress-project-management.git"
+  },
+  "keywords": [
+    "vitepress",
+    "vitepress-theme",
+    "kanban",
+    "project-management",
+    "markdown",
+    "vue"
+  ],
+  "scripts": {
+    "build": "esbuild src/plugins/markdownWriter.ts --format=esm --platform=node --bundle --external:gray-matter --external:vite --outfile=dist/plugin.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./plugin": "./dist/plugin.mjs"
+  },
+  "bin": {
+    "vitepress-theme-pm": "./src/cli.mjs"
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "peerDependencies": {
+    "vitepress": ">=1.0.0",
+    "vue": ">=3.3.0"
+  },
+  "devDependencies": {
+    "esbuild": ">=0.17.0"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3"
+  }
+}

package/src/Layout.vue

@@ -0,0 +1,15 @@
+<script setup lang="ts">
+import { useData } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+import Board from './components/Board.vue'
+
+const { frontmatter } = useData()
+</script>
+
+<template>
+  <DefaultTheme.Layout>
+    <template #page-top>
+      <Board v-if="frontmatter.board" />
+    </template>
+  </DefaultTheme.Layout>
+</template>

package/src/cli.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs'
+import path from 'node:path'
+import matter from 'gray-matter'
+
+const args = process.argv.slice(2)
+const command = args[0]
+
+if (command === 'ticket') {
+  createTicket(args.slice(1))
+} else {
+  console.log(`Usage:
+  vitepress-theme-pm ticket "Title"           Create a new ticket
+  vitepress-theme-pm ticket "Title" --status doing --priority high --tags core,ui
+
+Options:
+  --dir <path>       Tickets directory (default: tickets)
+  --status <status>  Initial status (default: backlog)
+  --priority <pri>   Priority: critical, high, medium, low (default: medium)
+  --tags <tags>      Comma-separated tags`)
+  process.exit(command ? 1 : 0)
+}
+
+function getMaxTicketId(ticketsDir) {
+  if (!fs.existsSync(ticketsDir)) return 0
+  const files = fs.readdirSync(ticketsDir).filter(f => f.endsWith('.md'))
+  let max = 0
+  for (const file of files) {
+    const raw = fs.readFileSync(path.join(ticketsDir, file), 'utf-8')
+    const parsed = matter(raw)
+    const id = Number(parsed.data.id)
+    if (id > max) max = id
+  }
+  return max
+}
+
+function parseArgs(args) {
+  let title = ''
+  let dir = 'tickets'
+  let status = 'backlog'
+  let priority = 'medium'
+  let tags = []
+
+  let i = 0
+  while (i < args.length) {
+    if (args[i] === '--dir') { dir = args[++i]; i++; continue }
+    if (args[i] === '--status') { status = args[++i]; i++; continue }
+    if (args[i] === '--priority') { priority = args[++i]; i++; continue }
+    if (args[i] === '--tags') { tags = args[++i].split(',').map(t => t.trim()).filter(Boolean); i++; continue }
+    if (!title) { title = args[i] }
+    i++
+  }
+
+  return { title, dir, status, priority, tags }
+}
+
+function readTicketPrefix(siteDir) {
+  const boardPath = path.join(siteDir, 'board.md')
+  if (!fs.existsSync(boardPath)) return null
+  try {
+    const raw = fs.readFileSync(boardPath, 'utf-8')
+    const parsed = matter(raw)
+    return parsed.data.ticketPrefix || null
+  } catch {
+    return null
+  }
+}
+
+function createTicket(args) {
+  const opts = parseArgs(args)
+
+  if (!opts.title) {
+    console.error('Error: title is required. Usage: vitepress-theme-pm ticket "My ticket title"')
+    process.exit(1)
+  }
+
+  const ticketsDir = path.resolve(process.cwd(), opts.dir)
+  if (!fs.existsSync(ticketsDir)) {
+    fs.mkdirSync(ticketsDir, { recursive: true })
+  }
+
+  const id = getMaxTicketId(ticketsDir) + 1
+  const frontmatter = {
+    id,
+    title: opts.title,
+    status: opts.status,
+    priority: opts.priority,
+  }
+  if (opts.tags.length > 0) {
+    frontmatter.tags = opts.tags
+  }
+
+  const content = matter.stringify('\n', frontmatter)
+  const filePath = path.join(ticketsDir, `${id}.md`)
+  fs.writeFileSync(filePath, content)
+
+  const prefix = readTicketPrefix(path.dirname(ticketsDir))
+  const displayId = prefix ? `${prefix}-${id}` : String(id)
+
+  console.log(`Created ${displayId}: ${opts.title}`)
+  console.log(`  File: ${path.relative(process.cwd(), filePath)}`)
+}

package/src/components/Board.vue

@@ -0,0 +1,200 @@
+<script setup lang="ts">
+import { ref, computed } from 'vue'
+import { useData } from 'vitepress'
+import type { Ticket, Column } from '../types'
+import { useDragDrop } from '../composables/useDragDrop'
+import { useTicketWriter } from '../composables/useTicketWriter'
+import BoardColumn from './BoardColumn.vue'
+import TicketDetail from './TicketDetail.vue'
+import '../styles/board.css'
+
+const { frontmatter } = useData()
+
+const columns = computed<Column[]>(() => frontmatter.value.columns || [])
+const ticketsDir = computed(() => frontmatter.value.ticketsDir || 'tickets')
+const ticketPrefix = computed(() => frontmatter.value.ticketPrefix || '')
+const defaultColumn = computed(() => frontmatter.value.defaultColumn || (columns.value.length > 0 ? columns.value[0].key : 'backlog'))
+
+const tickets = ref<Ticket[]>([])
+const selectedId = ref<number | null>(null)
+const draftTicket = ref<Ticket | null>(null)
+const filter = ref('')
+
+const { writeTicket } = useTicketWriter()
+
+// Load tickets from dev plugin or static JSON
+if (typeof window !== 'undefined') {
+  const url = import.meta.env.DEV
+    ? `/__vitepress_pm_tickets?dir=${encodeURIComponent(ticketsDir.value)}`
+    : `${import.meta.env.BASE_URL}__vitepress_pm_tickets/${encodeURIComponent(ticketsDir.value)}.json`
+
+  fetch(url)
+    .then(r => {
+      if (r.ok) return r.json()
+      throw new Error('not available')
+    })
+    .then((data: Ticket[]) => { tickets.value = data })
+    .catch(() => {})
+}
+
+function updateTicket(id: number, patch: Partial<Ticket>) {
+  tickets.value = tickets.value.map(t =>
+    t.id === id ? { ...t, ...patch } : t
+  )
+  const ticket = tickets.value.find(t => t.id === id)
+  if (ticket?.url) {
+    // Don't send url/id to the file writer
+    const { url: _url, id: _id, ...fields } = { ...patch } as any
+    if (Object.keys(fields).length > 0) {
+      writeTicket(ticket.url, fields)
+    }
+  }
+}
+
+function openNewTicket() {
+  draftTicket.value = {
+    id: 0,
+    title: 'New ticket',
+    status: defaultColumn.value,
+    priority: 'medium',
+    tags: [],
+    body: '',
+    url: '',
+  }
+}
+
+async function confirmCreate(draft: Ticket) {
+  if (import.meta.env.DEV) {
+    try {
+      const res = await fetch('/__vitepress_pm_create', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          dir: ticketsDir.value,
+          status: draft.status,
+          title: draft.title,
+          priority: draft.priority,
+          tags: draft.tags,
+          body: draft.body,
+        }),
+      })
+      if (!res.ok) throw new Error(await res.text())
+      const ticket: Ticket = await res.json()
+      tickets.value = [...tickets.value, ticket]
+      draftTicket.value = null
+      return
+    } catch (e) {
+      console.error('Failed to create ticket:', e)
+      return
+    }
+  }
+
+  // Production: create in-memory only
+  const maxId = tickets.value.reduce((m, t) => Math.max(m, t.id), 0)
+  const ticket: Ticket = {
+    id: maxId + 1,
+    title: draft.title,
+    status: draft.status,
+    priority: draft.priority,
+    tags: [...draft.tags],
+    body: draft.body,
+    url: '',
+  }
+  tickets.value = [...tickets.value, ticket]
+  draftTicket.value = null
+}
+
+function deleteTicket(id: number) {
+  if (confirm('Delete this ticket?')) {
+    tickets.value = tickets.value.filter(t => t.id !== id)
+    if (selectedId.value === id) selectedId.value = null
+  }
+}
+
+const filteredTickets = computed(() => {
+  if (!filter.value) return tickets.value
+  const q = filter.value.toLowerCase()
+  return tickets.value.filter(t =>
+    t.title.toLowerCase().includes(q) ||
+    t.tags.some(tag => tag.includes(q)) ||
+    formatId(t.id).toLowerCase().includes(q)
+  )
+})
+
+const selectedTicket = computed(() =>
+  tickets.value.find(t => t.id === selectedId.value) || null
+)
+
+function columnTickets(key: string) {
+  return filteredTickets.value.filter(t => t.status === key)
+}
+
+function formatId(id: number): string {
+  return ticketPrefix.value ? `${ticketPrefix.value}-${id}` : String(id)
+}
+
+const { dragOverColumn, handleDragStart, handleDragEnd, handleDragOver, handleDragLeave, handleDrop } =
+  useDragDrop((ticketId, targetColumn) => {
+    updateTicket(Number(ticketId), { status: targetColumn })
+  })
+</script>
+
+<template>
+  <div style="display: flex; flex-direction: column; height: calc(100vh - var(--vp-nav-height) - 1px); overflow: hidden">
+    <!-- Filter bar -->
+    <div style="padding: 8px 16px; border-bottom: 1px solid #2d3748; flex-shrink: 0; display: flex; align-items: center; gap: 8px">
+      <input
+        v-model="filter"
+        placeholder="Filter tickets..."
+        style="font-size: 12px; padding: 5px 10px; background: #171923; border: 1px solid #2d3748; border-radius: 5px; color: #e2e8f0; outline: none; width: 200px"
+      >
+      <button
+        title="New ticket"
+        style="font-size: 13px; padding: 4px 12px; background: #2d3748; border: 1px solid #4a5568; border-radius: 5px; color: #e2e8f0; cursor: pointer; font-weight: 600; line-height: 1.2"
+        @click="openNewTicket"
+      >+ New</button>
+    </div>
+
+    <!-- Columns -->
+    <div class="board-columns" style="flex: 1; display: flex; overflow: auto; padding: 12px 8px">
+      <BoardColumn
+        v-for="col in columns"
+        :key="col.key"
+        :column="col"
+        :tickets="columnTickets(col.key)"
+        :selected-id="selectedId"
+        :ticket-prefix="ticketPrefix"
+        :is-over="dragOverColumn === col.key"
+        @select="(id: number) => selectedId = selectedId === id ? null : id"
+        @dragstart="(e: DragEvent, id: number) => handleDragStart(e, String(id))"
+        @dragend="handleDragEnd"
+        @dragover="(e: DragEvent) => handleDragOver(e, col.key)"
+        @dragleave="handleDragLeave"
+        @drop="(e: DragEvent) => handleDrop(e, col.key)"
+      />
+    </div>
+
+    <!-- Create modal -->
+    <TicketDetail
+      v-if="draftTicket"
+      :ticket="draftTicket"
+      :columns="columns"
+      :ticket-prefix="ticketPrefix"
+      :create-mode="true"
+      @close="draftTicket = null"
+      @update="(_id: number, patch: Partial<Ticket>) => { draftTicket = { ...draftTicket!, ...patch } }"
+      @create="confirmCreate(draftTicket!)"
+    />
+
+    <!-- Edit modal -->
+    <TicketDetail
+      v-else-if="selectedTicket"
+      :ticket="selectedTicket"
+      :columns="columns"
+      :ticket-prefix="ticketPrefix"
+      @close="selectedId = null"
+      @update="updateTicket"
+      @delete="deleteTicket"
+    />
+  </div>
+</template>