docs: add article markdown export implementation plan

Add a task-by-task implementation plan for public post markdown export, including TDD checkpoints, integration steps, and manual acceptance verification. Made-with: Cursor
2 weeks ago · 2d5e027f82
1 changed files with 275 additions and 0 deletions
--- a/docs/superpowers/plans/2026-04-23-article-markdown-export-implementation-plan.md
+++ b/docs/superpowers/plans/2026-04-23-article-markdown-export-implementation-plan.md
@ -0,0 +1,275 @@
+# Article Markdown Export Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a visitor-available `.md` export button on public post detail pages that downloads `bodyMarkdown` and normalizes site-relative image URLs to absolute URLs.
+
+**Architecture:** Keep export fully client-side in the existing public post detail page to avoid adding new server endpoints. Add a focused utility module to normalize markdown image URLs and trigger downloads, with unit tests for URL handling rules. Integrate button states and toast feedback in `app/pages/@[publicSlug]/posts/[postSlug].vue` without changing existing post loading/edit/comment behaviors.
+
+**Tech Stack:** Nuxt 4, Vue 3 `<script setup>`, Bun test (`bun:test`), existing Nuxt UI `UButton` and `useToast`.
+
+**Spec:** `docs/superpowers/specs/2026-04-23-article-markdown-export-design.md`
+
+---
+
+## File Structure Map
+
+- Create `app/utils/markdown-export.ts`
+  - Single responsibility: normalize markdown image URLs + download markdown file in browser.
+- Create `app/utils/markdown-export.test.ts`
+  - Unit tests for normalization and filename helpers.
+- Modify `app/pages/@[publicSlug]/posts/[postSlug].vue`
+  - Add export action wiring, button state, and success/failure toast UX in existing action row.
+
+---
+
+### Task 1: Add Markdown Export Utility with TDD
+
+**Files:**
+- Create: `app/utils/markdown-export.ts`
+- Test: `app/utils/markdown-export.test.ts`
+
+- [ ] **Step 1: Write failing tests for URL normalization and filename fallback**
+
+```ts
+import { describe, expect, test } from "bun:test";
+import { buildMarkdownExportFileName, normalizeMarkdownImageUrls } from "./markdown-export";
+
+describe("normalizeMarkdownImageUrls", () => {
+  test("converts site-relative image links to absolute", () => {
+    const input = "cover ![](/public/assets/u1/a.webp)";
+    expect(normalizeMarkdownImageUrls(input, "https://example.com")).toBe(
+      "cover ![](https://example.com/public/assets/u1/a.webp)",
+    );
+  });
+
+  test("keeps absolute http/https image links unchanged", () => {
+    const input = "![](https://cdn.example.com/a.png)\n![](http://cdn.example.com/b.png)";
+    expect(normalizeMarkdownImageUrls(input, "https://example.com")).toBe(input);
+  });
+
+  test("keeps protocol-relative and data URI image links unchanged", () => {
+    const input = "![](//cdn.example.com/a.png)\n![](data:image/png;base64,AAAA)";
+    expect(normalizeMarkdownImageUrls(input, "https://example.com")).toBe(input);
+  });
+
+  test("does not rewrite normal markdown links", () => {
+    const input = "[asset](/public/assets/u1/a.webp)";
+    expect(normalizeMarkdownImageUrls(input, "https://example.com")).toBe(input);
+  });
+});
+
+describe("buildMarkdownExportFileName", () => {
+  test("uses slug when present", () => {
+    expect(buildMarkdownExportFileName({ slug: "hello-world", id: 12 })).toBe("hello-world.md");
+  });
+
+  test("falls back to post-id when slug is blank", () => {
+    expect(buildMarkdownExportFileName({ slug: "  ", id: 12 })).toBe("post-12.md");
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify failure**
+
+Run: `bun test app/utils/markdown-export.test.ts`  
+Expected: FAIL with module/function not found.
+
+- [ ] **Step 3: Implement minimal utility module**
+
+```ts
+const IMAGE_LINK_RE = /!\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+
+function normalizeOrigin(origin: string): string {
+  return origin.replace(/\/+$/, "");
+}
+
+function isAbsoluteLike(url: string): boolean {
+  return /^(https?:)?\/\//i.test(url) || /^data:/i.test(url);
+}
+
+export function normalizeMarkdownImageUrls(markdown: string, origin: string): string {
+  const base = normalizeOrigin(origin);
+  return markdown.replace(IMAGE_LINK_RE, (full, alt, url) => {
+    if (!url.startsWith("/") || isAbsoluteLike(url)) {
+      return full;
+    }
+    return `![${alt}](${base}${url})`;
+  });
+}
+
+export function buildMarkdownExportFileName(input: { slug: string; id: number }): string {
+  const slug = input.slug.trim();
+  return slug.length > 0 ? `${slug}.md` : `post-${input.id}.md`;
+}
+
+export function downloadMarkdownFile(filename: string, content: string): void {
+  const blob = new Blob([content], { type: "text/markdown;charset=utf-8" });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  URL.revokeObjectURL(url);
+}
+```
+
+- [ ] **Step 4: Run tests to verify pass**
+
+Run: `bun test app/utils/markdown-export.test.ts`  
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app/utils/markdown-export.ts app/utils/markdown-export.test.ts
+git commit -m "feat(export): add markdown export utilities with url normalization tests"
+```
+
+---
+
+### Task 2: Integrate Export Button into Public Post Detail Page
+
+**Files:**
+- Modify: `app/pages/@[publicSlug]/posts/[postSlug].vue`
+
+- [ ] **Step 1: Add focused failing assertion test for helper contract (guard against regressions)**
+
+```ts
+import { describe, expect, test } from "bun:test";
+import { normalizeMarkdownImageUrls } from "../../../utils/markdown-export";
+
+describe("public post export contract", () => {
+  test("normalizes site image link for page-export flow", () => {
+    const body = "![img](/public/assets/x.png)";
+    expect(normalizeMarkdownImageUrls(body, "https://site.local")).toContain(
+      "https://site.local/public/assets/x.png",
+    );
+  });
+});
+```
+
+Run location suggestion: append to `app/utils/markdown-export.test.ts` rather than introducing a Vue SFC test harness.
+
+- [ ] **Step 2: Run test to verify it fails first (if newly added case)**
+
+Run: `bun test app/utils/markdown-export.test.ts`  
+Expected: FAIL if new case uncovers a parsing gap; otherwise treat as green safety net and proceed.
+
+- [ ] **Step 3: Implement page integration (imports, handler, toast, button)**
+
+```ts
+import {
+  buildMarkdownExportFileName,
+  downloadMarkdownFile,
+  normalizeMarkdownImageUrls,
+} from "../../../utils/markdown-export";
+
+const toast = useToast();
+
+function exportMarkdown() {
+  if (!data.value) {
+    return;
+  }
+  try {
+    const origin = window.location.origin;
+    const content = normalizeMarkdownImageUrls(data.value.bodyMarkdown || "", origin);
+    const filename = buildMarkdownExportFileName({ slug: data.value.slug, id: data.value.id });
+    downloadMarkdownFile(filename, content);
+    toast.add({ title: "已导出 Markdown", color: "success" });
+  } catch {
+    toast.add({ title: "导出失败，请稍后重试", color: "error" });
+  }
+}
+```
+
+```vue
+<UButton
+  v-if="data"
+  variant="soft"
+  color="neutral"
+  size="sm"
+  :disabled="pending"
+  @click="exportMarkdown"
+>
+  导出 .md
+</UButton>
+```
+
+- [ ] **Step 4: Run test + build-level sanity check**
+
+Run: `bun test app/utils/markdown-export.test.ts && bun run build`  
+Expected: tests PASS and Nuxt build succeeds.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app/pages/@[publicSlug]/posts/[postSlug].vue app/utils/markdown-export.test.ts
+git commit -m "feat(posts): add public post markdown export action"
+```
+
+---
+
+### Task 3: Manual Acceptance Verification Against Spec
+
+**Files:**
+- Verify: `app/pages/@[publicSlug]/posts/[postSlug].vue`
+- Verify: `docs/superpowers/specs/2026-04-23-article-markdown-export-design.md`
+
+- [ ] **Step 1: Start app for manual checks**
+
+Run: `bun run dev`  
+Expected: app starts and public post detail page is reachable.
+
+- [ ] **Step 2: Verify core export behaviors**
+
+Manual checklist:
+1. Visit `/<public post url>` while logged out; confirm `导出 .md` is visible.
+2. Click export; confirm file downloads as `<slug>.md` or `post-<id>.md`.
+3. Open exported file and confirm正文内容等于 `bodyMarkdown`（仅图片链接归一化例外）。
+
+- [ ] **Step 3: Verify image URL normalization and no-overwrite rules**
+
+Use a post containing all sample links and validate output:
+
+```md
+![local](/public/assets/u1/a.webp)
+![abs](https://cdn.example.com/a.png)
+![proto](//cdn.example.com/a.png)
+![data](data:image/png;base64,AAAA)
+[plain](/public/assets/u1/a.webp)
+```
+
+Expected in exported file:
+- first link rewritten to absolute URL with current origin
+- other four lines unchanged except markdown-preserving formatting
+
+- [ ] **Step 4: Verify error and state behavior**
+
+Manual checklist:
+1. While loading (`pending`), export button should be disabled.
+2. On not-found/error page (`error && !data`), export button should not render.
+3. If `bodyMarkdown` empty, exported file exists and is empty content.
+
+- [ ] **Step 5: Commit any small UX copy tweaks from manual verification**
+
+```bash
+git add app/pages/@[publicSlug]/posts/[postSlug].vue
+git commit -m "chore(export): polish markdown export ux states after manual verification"
+```
+
+---
+
+## Self-Review
+
+- **Spec coverage:**  
+  - Public detail page export entry: Task 2  
+  - Visitor access: Task 2 + Task 3 validation  
+  - Export content is body only: Task 2 handler  
+  - Relative image URL to absolute conversion: Task 1 + Task 3  
+  - UX states/toasts/error handling: Task 2 + Task 3
+- **Placeholder scan:** No TODO/TBD placeholders; each code-changing step has concrete snippet and command.
+- **Type consistency:** `buildMarkdownExportFileName`, `normalizeMarkdownImageUrls`, `downloadMarkdownFile` names are consistent across test and integration steps.
+