classroomio/prd/copy-page-as-markdown/README.md

Copy Page as Markdown PRD

Status

• Draft (not started)

Purpose

Give learners on public course pages a one-click way to export lesson content as Markdown and hand it off to an AI tool. The pattern is the same split-button found on Vercel, Next.js, and shadcn-svelte docs:

• Primary "Copy Page" copies the lesson as Markdown to the clipboard.
• Chevron dropdown exposes:
  • View as Markdown
  • Open in ChatGPT
  • Open in Claude

Teachers control whether this surface appears, per course, via a setting in course settings.

Motivation

Learners increasingly mix course content with AI tools — pasting lesson text into ChatGPT/Claude to ask follow-up questions, get worked examples, or debug exercises. Today they manually select-and-copy from the page, which captures HTML noise, broken whitespace, and embedded video chrome. Shipping a first-class "Copy Page" action:

1. Removes the friction of switching between the lesson and an AI tool.
2. Produces clean Markdown (no iframes, no video embeds, no rich-text artefacts) so the AI tool receives high-quality context.
3. Matches the convention learners already see on modern documentation sites — feels native to anyone who uses them.

Scope

In scope (v1)

• Public lesson pages only: /course/[slug]/lesson/[itemSlug].
• Per-course toggle in course settings (metadata.allowMarkdownExport). Default: off.
• Server-side HTML → Markdown conversion with videos stripped.
• A bookmarkable .../markdown URL that returns the lesson as text/markdown.
• Split button on the public lesson shell with four actions: Copy Page, View as Markdown, Open in ChatGPT, Open in Claude.

Out of scope (v1)

• Course landing pages, section pages, and any non-lesson public surface.
• Open in v0 (skipped — most lessons aren't UI/component focused).
• Bulk export of an entire course as a single Markdown document.
• Authenticated dashboard surfaces (only public pages get the action).
• Localised Markdown output (initial release exports the lesson's current locale verbatim).

Confirmed Decisions

1. Scope is lesson pages only. Landing and section pages are deferred until there is signal that learners want them.
2. Per-course toggle is stored on course.metadata. This matches the existing pattern used by lessonDownload, grading, and allowNewStudent, so no new column or migration is required.
3. Default value is off. Teachers must explicitly opt in. This avoids silently exposing course content as easily copyable Markdown to courses created before the feature shipped.
4. HTML → Markdown conversion runs on the server, not in the browser, so the turndown dependency does not ship to learners and a real bookmarkable .md URL exists.
5. Videos are excluded from the Markdown output. <iframe>, <video>, and known video-host anchor tags (YouTube, Vimeo, Loom) are stripped before conversion.
6. The same /markdown URL serves three purposes: target of "View as Markdown", source the client fetches for "Copy Page", and the URL embedded in the AI prompt templates.
7. Open in ChatGPT / Open in Claude use a course-specific prompt template containing the lesson title, course title, and the public lesson URL.
8. No v0 destination in v1. Revisit if usage data shows demand from teachers running code-heavy courses.

User Stories

• As a learner reading a public course lesson, I want to copy the lesson as Markdown so I can paste clean context into ChatGPT or Claude.
• As a learner reading a long technical lesson, I want a "View as Markdown" URL so I can read it in a distraction-free format and link to it.
• As a teacher publishing a public course, I want to choose whether learners can export my lesson content, so I retain control over how my material is reused.
• As a teacher with a paid course, I want this feature off by default so my content is not trivially extractable without my consent.

Feature Detail

Teacher-facing — Course Settings toggle

A new Switch is added to the existing course settings page, next to lessonDownload:

• Label: "Allow learners to copy lesson pages as Markdown"
• Helper text: "When enabled, public lesson pages show a Copy Page button that exports the lesson content (excluding videos) as Markdown."
• Off by default for both new and existing courses.

Persisted via the existing course update endpoint as metadata.allowMarkdownExport: boolean.

Learner-facing — Public lesson page

When the course has metadata.allowMarkdownExport === true, the public lesson page shell renders a split button in the top-right toolbar slot:

[ 📋 Copy Page | ⌄ ]
              │
              ├── M↓  View as Markdown
              ├── 💬  Open in ChatGPT
              └── ✻   Open in Claude

Primary "Copy Page" button

1. Fetches /course/<slug>/lesson/<itemSlug>/markdown (returns text/markdown).
2. Writes the response body to the clipboard via the existing copyToClipboard utility.
3. Shows a Copied snackbar on success, error snackbar on failure.

View as Markdown

Opens /course/<slug>/lesson/<itemSlug>/markdown in a new tab. Browser renders the raw Markdown inline (response is text/markdown; charset=utf-8, no Content-Disposition: attachment so it does not download).

Open in ChatGPT

Opens https://chatgpt.com/?prompt=<encoded prompt> in a new tab.

Open in Claude

Opens https://claude.ai/new?q=<encoded prompt> in a new tab. The exact param name (q vs prompt) is verified during implementation; if neither is supported the button falls back to opening claude.ai/new so the learner can paste manually.

Prompt template (shared by ChatGPT and Claude)

I'm studying "<lesson title>" from the course "<course title>" (<public lesson URL>).
Help me understand the concepts, give examples, or help debug based on it.

Markdown output format

The endpoint returns a single Markdown document:

# <course title> — <lesson title>

<converted lesson body>

Conversion rules:

• HTML body is first run through the existing sanitize-html.ts pipeline.
• <iframe>, <video>, and <a> tags whose href matches YouTube, Vimeo, or Loom are dropped (defence-in-depth, even though sanitiser strips <iframe>/<video> already).
• Remaining HTML is converted via turndown with sensible defaults: ATX headings, fenced code blocks, - bullets.
• Output is plain UTF-8 with \n line endings.

Gating

GET /course/<slug>/lesson/<itemSlug>/markdown returns 404 when the course has metadata.allowMarkdownExport !== true. This makes the toggle authoritative — the URL cannot be used to bypass the teacher's preference.

Technical Notes

Touched files / new files

Purpose	Path
Course metadata type	packages/db/src/schema.ts (extend the inline metadata type on courses)
Validation schema	packages/utils/src/validation/course/course.ts (ZCourseMetadata)
Settings UI	apps/dashboard/src/lib/features/course/pages/settings.svelte
Translations	apps/dashboard/src/lib/utils/translations/en.json
New: HTML→MD util	apps/api/src/utils/html-to-markdown.ts
New: markdown route	apps/api/src/routes/course/lesson-markdown.ts (mounted via the course aggregate router per CLAUDE.md rules)
New: copy-page button	packages/ui/src/custom/public-course/copy-page-button.svelte
Public lesson wiring	apps/dashboard/src/routes/(org-site)/course/[slug]/lesson/[itemSlug]/+page.svelte and the topRight slot on packages/ui/src/custom/public-course/shell.svelte
Reused: clipboard util	apps/dashboard/src/lib/utils/functions/formatYoutubeVideo.ts (copyToClipboard)
Reused: dropdown primitives	packages/ui/src/base/dropdown-menu/
Reused: HTML sanitiser	apps/api/src/utils/sanitize-html.ts
New dep	turndown + @types/turndown in apps/api/package.json

No database migration is required — the toggle lives in the existing JSONB metadata column.

Translation keys

• course.navItem.settings.allow_markdown_export
• course.navItem.settings.allow_markdown_export_description
• public_course.copy_page.copy
• public_course.copy_page.view_as_markdown
• public_course.copy_page.open_in_chatgpt
• public_course.copy_page.open_in_claude
• public_course.copy_page.copied

Risks & Open Questions

1. Claude URL parameter. claude.ai/new?q=… is the current convention but is not officially documented. Implementation must verify before merge and fall back to a no-parameter open if it breaks.
2. Sanitiser/turndown interaction. Some tiptap output (custom embed nodes, fancy tables) may produce odd Markdown. The PR should include a smoke test with at least one rich lesson (mixed headings, images, code blocks, a table, and a YouTube embed).
3. Markdown URL as exfiltration vector. The endpoint is gated by metadata.allowMarkdownExport, but teachers may not realise that toggling the switch on makes a public, scrapable URL available. Helper text on the setting calls this out explicitly.
4. Future surfaces. If learners ask for "copy entire course" or "copy section", we will revisit; the v1 endpoint shape (/lesson/<itemSlug>/markdown) leaves room for sibling endpoints like /section/<sectionSlug>/markdown.

Verification

End-to-end checks before sign-off:

1. pnpm --filter @cio/db build succeeds with the extended metadata type.
2. pnpm --filter @cio/api build succeeds with the new route and turndown dep.
3. Toggling the setting in course settings persists across reload.
4. With the toggle off, the Copy Page button is not rendered on the public lesson page, and a direct GET /…/markdown returns 404.
5. With the toggle on:
   • Copy Page → snackbar Copied; pasted result is clean Markdown with no <iframe>/<video>.
   • View as Markdown → new tab shows the raw Markdown inline.
   • Open in ChatGPT → new tab at chatgpt.com/?prompt=… with the templated prompt and current public URL.
   • Open in Claude → new tab at claude.ai/new?q=… with the templated prompt and current public URL.
6. Lesson with embedded YouTube / Loom iframes — Markdown output has those stripped, surrounding text intact.