docs: fill more feature gaps + correct existing pages

web/src/pages/DocsPage/WipBanner.tsx

@@ -3,7 +3,7 @@ import styles from './DocsPage.module.css';
 export function WipBanner() {
   return (
     <div className={styles.wipBanner} role="note">
-      These docs are being rewritten. If something looks wrong,{' '}
+      These docs are being rewritten with help from AI. If something looks wrong,{' '}
       <a
         href="https://github.com/2anki/server/issues/new"
         target="_blank"

web/src/pages/DocsPage/content/cards/card-options.md

@@ -11,31 +11,84 @@ Card options change how 2anki turns your source into flashcards. Most are off-or
 - **In account settings** — `Settings → Card options` saves defaults that apply to every new upload. You can still override per upload.
 - **Per Notion page** — when you convert through the Notion integration, options are saved against the page so the next sync uses the same shape.
 
-## Reference
+## Deck shape
+
+| Option | Default | What it does |
+|---|---|---|
+| Deck name | — | Custom name for the downloaded `.apkg`. Leave empty to use the source's name. |
+| Font size | 20 | Base font size for card text, in pixels. |
+| Toggle mode | Close nested toggles | Controls whether nested toggles render open or closed on the card back. |
+| Page emoji | Icon first | Where the page emoji shows up in the deck title — first, last, or disabled. |
+| Basic note type | `n2a-basic` | The Anki note type name 2anki uses for basic cards. Change it to plug your own template in. |
+| Cloze note type | `n2a-cloze` | Same, for cloze cards. |
+| Input note type | `n2a-input` | Same, for typed-input cards. |
+
+## Card content
 
 | Option | Default | What it does |
 |---|---|---|
-| Add Notion Link | Off | Adds a link to the Notion page where the toggle was created. Use this with **Use Notion ID** to avoid duplicates. |
-| Use Notion ID | On | Uses Notion's ID to match cards across re-uploads instead of regenerating IDs from the field text. Reduces duplicates. |
 | Use All Toggle Lists | On | Picks up toggle lists nested anywhere in the page. Off means only top-level toggles are used. |
 | Use Plain Text for Back | Off | Strips formatting from the back of cards so only the text content remains. |
-| Enable Cherry Picking Using 🍒 Emoji | Off | Only creates cards from toggles that contain a 🍒 emoji. Useful for picking out a few cards from a long page. |
-| Only Create Flashcards From Toggles That Don't Have The 🥑 Emoji | Off | Skips toggles that contain a 🥑 emoji. Useful for marking parts of a page as not-yet-ready. |
-| Treat Strikethrough as Tags | Off | Treats strikethrough text as Anki tags. Strikethrough inside a toggle becomes a tag local to that card; outside, it's a global tag. |
+| Maximum One Toggle Per Card | On | Splits nested toggles into separate cards instead of stacking them in one. |
+| Preserve Newlines in the Toggle Header and Body | On | Keeps SHIFT-Enter line breaks inside toggles instead of collapsing them. |
+| Markdown Nested Bullet Points | On | Reads Markdown bullet hierarchies (Obsidian-style) as front/back pairs. |
+| Disable Indented Bullets | Off | Stops indented bullets from each becoming their own card. |
+
+## Card types
+
+| Option | Default | What it does |
+|---|---|---|
 | Cloze Deletion | On | Creates cloze cards from inline `code` snippets. |
 | Treat Bold Text as Input | Off | Bold text is removed and turned into a typed-answer field. Good for fact recall. |
 | Basic and Reversed | Off | Creates the front/back card and a reversed copy. |
 | Just the Reversed Flashcards | Off | Only creates the reversed card. Useful when the back is more useful as a prompt (e.g. an image). |
+
+## Filtering
+
+| Option | Default | What it does |
+|---|---|---|
+| Enable Cherry Picking Using 🍒 Emoji | Off | Only creates cards from toggles that contain a 🍒 emoji. Useful for picking out a few cards from a long page. |
+| Only Create Flashcards From Toggles That Don't Have The 🥑 Emoji | Off | Skips toggles that contain a 🥑 emoji. Useful for marking parts of a page as not-yet-ready. |
+| Treat Strikethrough as Tags | Off | Treats strikethrough text as Anki tags. Strikethrough inside a toggle becomes a tag local to that card; outside, it's a global tag. |
+
+## Links and formatting
+
+| Option | Default | What it does |
+|---|---|---|
+| Add Notion Link | Off | Adds a link to the Notion page where the toggle was created. Use this with **Use Notion ID** to avoid duplicates. |
+| Use Notion ID | On | Uses Notion's ID to match cards across re-uploads instead of regenerating IDs from the field text. Reduces duplicates. |
 | Remove Underlines | Off | Drops underline formatting. Helps when Notion underlines clash with Anki's link styling. |
-| Maximum One Toggle Per Card | On | Splits nested toggles into separate cards instead of stacking them in one. |
 | Remove the MP3 Links Created From Audio Files | On | Strips the auto-generated `.mp3` links left behind by some Notion exports. |
-| Preserve Newlines in the Toggle Header and Body | On | Keeps SHIFT-Enter line breaks inside toggles instead of collapsing them. |
+
+## PDF and AI
+
+| Option | Default | What it does |
+|---|---|---|
 | Process PDF Files | On | Converts PDFs found in ZIP uploads. Turn off to skip PDFs and speed up large archives. |
-| Markdown Nested Bullet Points | On | Reads Markdown bullet hierarchies (Obsidian-style) as front/back pairs. |
 | Generate Questions from Single PDF File Uploads | Off | Sends the PDF to Google Vertex AI to generate questions. Paid; sends content to Google Cloud. |
-| Disable Indented Bullets | Off | Stops indented bullets from each becoming their own card. |
-| Convert Image Quiz HTML to Anki Cards | Off | Uses OCR to pull image-and-answer pairs from HTML quizzes. Premium experimental. |
 | Generate Flashcards with Claude AI | Off | Sends content to Anthropic Claude and uses its output as the deck. Paid. |
+| User instructions | — | Free-form prompt sent to Claude when **Generate Flashcards with Claude AI** is on. Example: *"Focus on USMLE high-yield. Skip the introduction."* |
+| Convert Image Quiz HTML to Anki Cards | Off | Uses OCR to pull image-and-answer pairs from HTML quizzes. Premium experimental. |
+
+## Multiple choice
+
+These only fire when **Enable MCQ** is on. See [Multiple choice questions](/documentation/cards/mcq) for the full guide.
+
+| Option | Default | What it does |
+|---|---|---|
+| Enable MCQ | Off | Detects multiple-choice toggles and produces interactive MCQ cards instead of basic ones. |
+| Show choices | Show up front | Whether the options appear on the front of the card, or behind a button you click to reveal. |
+| Shuffle options | On | Randomize the option order on every review so position can't be a hint. |
+| TTS for the question | Don't speak | Read the question aloud. Languages: English (US), Spanish, French, German, Japanese, Mandarin (Simplified), Portuguese (Brazil). |
+| TTS for the correct answer | Don't speak | Read the correct answer aloud. Same language list. |
+| TTS for extra | Don't speak | Read the explanation aloud. Same language list. |
+
+## Debugging
+
+| Option | Default | What it does |
+|---|---|---|
 | Share Files for Debugging When Conversion Fails | Off | If a conversion fails, sends the file and error details to the 2anki team. Off by default to keep your notes private. |
 
-The option keys 2anki uses internally (handy if you're filing a bug report): `add-notion-link`, `use-notion-id`, `all`, `paragraph`, `cherry`, `avocado`, `tags`, `cloze`, `enable-input`, `basic-reversed`, `reversed`, `no-underline`, `max-one-toggle-per-card`, `remove-mp3-links`, `perserve-newlines`, `process-pdfs`, `markdown-nested-bullet-points`, `vertex-ai-pdf-questions`, `disable-indented-bullets`, `image-quiz-html-to-anki`, `claude-ai-flashcards`, `share-files-for-debugging`.
+## Internal option keys
+
+The option keys 2anki uses internally (handy if you're filing a bug report): `add-notion-link`, `use-notion-id`, `all`, `paragraph`, `cherry`, `avocado`, `tags`, `cloze`, `enable-input`, `basic-reversed`, `reversed`, `no-underline`, `max-one-toggle-per-card`, `remove-mp3-links`, `perserve-newlines`, `process-pdfs`, `markdown-nested-bullet-points`, `vertex-ai-pdf-questions`, `disable-indented-bullets`, `image-quiz-html-to-anki`, `claude-ai-flashcards`, `share-files-for-debugging`, `mcq-enabled`, `mcq-show-choices`, `mcq-shuffle`, `mcq-tts-question`, `mcq-tts-correct-answer`, `mcq-tts-extra`, `font-size`, `toggle-mode`, `page-emoji`, `basic_model_name`, `cloze_model_name`, `input_model_name`, `user-instructions`.

web/src/pages/DocsPage/content/cards/image-occlusion.md

@@ -0,0 +1,61 @@
+---
+title: Image occlusion
+description: Cover parts of an image and recall them — anatomy, diagrams, maps, screenshots.
+---
+
+Image occlusion cards show you a picture with bits hidden. You try to recall what's behind the cover, then flip the card to see if you got it right. The canvas tool at [2anki.net/image-occlusion](https://2anki.net/image-occlusion) lets you draw the covers yourself — no Anki add-on, no plugin install.
+
+**Plan:** Free for image upload. Importing images from Notion needs Subscription or Lifetime.
+
+## When to use this
+
+- You're studying something visual where the layout itself is the answer — anatomy diagrams, brain regions, chemical structures, ECGs, maps, UI screenshots, code diagrams.
+- A basic question/answer card would be slower than just seeing the picture and recalling the labels.
+- You already have a diagram with labels and want to test yourself on those labels in place.
+
+If your source is text — toggles, bullets, prose — basic or cloze cards are faster. Image occlusion is only worth the setup for genuinely spatial content.
+
+## Build a deck
+
+1. Open [2anki.net/image-occlusion](https://2anki.net/image-occlusion).
+2. Name the deck (the field at the top of the left panel). Defaults to "My image deck".
+3. Add images. Three ways:
+   - **Upload** — drag images into the queue or use the file picker.
+   - **Paste** — copy an image to your clipboard (screenshot tool, a Notion page, anywhere) and paste anywhere on the page.
+   - **Import from Notion** — click the Notion button on the queue if you're signed in and connected. Pick images from your Notion pages. This path needs a paid plan.
+4. Click an image in the queue to load it onto the canvas on the right.
+5. Draw a rectangle on each part you want to hide. Each box becomes one flashcard. Add a label to each box if you want extra context on the card back.
+6. (Optional) Add a header — short text above the image — to give the card a title or a question stem.
+7. Repeat for every image in the queue.
+8. Pick a mode at the bottom of the left panel:
+   - **Hide all, reveal one** — every box is covered; only the one you're studying is shown when you flip.
+   - **Hide one at a time** — only the box you're studying is covered; everything else stays visible.
+9. Click **Download deck** to get the `.apkg`. Open it in Anki.
+
+:::tip
+The canvas is much easier to use on a laptop or desktop than on a phone. Anki review afterwards works fine on any device.
+:::
+
+## Drafts and saving
+
+Signed-in users get auto-save: changes to deck name, mode, header, and boxes are saved as a draft every second or so. Close the tab and your work is still there when you come back. Drafts are removed after a successful download.
+
+Anonymous users (no sign-in) can still build a deck and download it, but the work isn't saved between sessions.
+
+## Hide all vs. hide one — what changes
+
+For a single image with three labelled boxes, **Hide all** creates 3 cards: each card shows the image with all three boxes covered, with one box revealed on the back. **Hide one** creates 3 cards too, but each shows the image with two boxes visible and one covered, then the covered one revealed.
+
+Use **Hide all** when knowing one label shouldn't give away the others (it's harder). Use **Hide one** when the surrounding labels are useful context (it's easier and faster).
+
+## Common mistakes
+
+- **No boxes drawn.** The **Download deck** button stays disabled until at least one image has a box on it. The card count next to the button is your guide — make sure it's not zero.
+- **Tiny boxes.** A box smaller than ~20 pixels is hard to click on phone review. Draw covers that fit the thing you're hiding plus a little padding.
+- **Trying to crop the image.** The boxes hide content; they don't crop. To trim the image, edit it before uploading.
+
+## Related
+
+- [Card types](/documentation/cards/card-types) — basic, cloze, input, MCQ
+- [Card options](/documentation/cards/card-options) — the rest of the conversion settings
+- [Limits and quotas](/documentation/help/limits) — what each plan includes

web/src/pages/DocsPage/content/cards/notion-blocks.md

@@ -25,23 +25,32 @@ These blocks are rendered in the exported deck.
 - [x] [Video](https://developers.notion.com/reference/block#video-blocks)
 - [x] [Audio](https://developers.notion.com/reference/block#audio-blocks)
 - [x] [File](https://developers.notion.com/reference/block#file-blocks)
-- [x] [PDF embed](https://developers.notion.com/reference/block#pdf-blocks)
 - [x] [Embed](https://developers.notion.com/reference/block#embed-blocks)
 - [x] [Bookmark](https://developers.notion.com/reference/block#bookmark-blocks)
 - [x] [Link to page](https://developers.notion.com/reference/block#link-to-page-blocks)
-- [x] [Child page](https://developers.notion.com/reference/block#child-page-blocks)
+- [x] [Child page](https://developers.notion.com/reference/block#child-page-blocks) — also usable as a sub-deck via [Parser rules](/documentation/cards/parser-rules).
 - [x] [Column list and column](https://developers.notion.com/reference/block#column-list-and-column-blocks)
 - [x] [Table](https://developers.notion.com/reference/block#table-blocks) and [Table row](https://developers.notion.com/reference/block#table-row-blocks) — one row, one card. Column 1 is the front, column 2 is the back. Turn on the **Table** chip in your rule to opt in. If the table has a header row, the first row is skipped. Columns 3 and beyond show up on the back as a small inline table.
 
+## Sub-deck-only
+
+These blocks don't render as cards, but they can structure your deck when used in [Parser rules](/documentation/cards/parser-rules):
+
+- [Child database](https://developers.notion.com/reference/block#child-database-blocks) — pick it as a sub-deck source. The database's rows then convert through the table path.
+
 ## Unsupported
 
-These blocks are skipped or rendered as a fallback.
+These blocks are skipped or rendered as a fallback. If one of them shows up on a card as raw text like `unsupported: <type>`, that's the fallback firing.
 
+- [ ] [PDF](https://developers.notion.com/reference/block#pdf-blocks) — Notion's embedded PDF block. Upload the PDF file directly through the [upload page](/documentation/start-here/upload-a-file) instead.
+- [ ] [Heading 4](https://developers.notion.com/reference/block#heading) — Notion's deepest heading level. H1, H2, and H3 work; H4 doesn't.
 - [ ] [Table of contents](https://developers.notion.com/reference/block#table-of-contents-blocks)
-- [ ] [Child database](https://developers.notion.com/reference/block#child-database-blocks)
 - [ ] [Breadcrumb](https://developers.notion.com/reference/block#breadcrumb-blocks)
 - [ ] [Link preview](https://developers.notion.com/reference/block#link-preview-blocks)
 - [ ] [Template](https://developers.notion.com/reference/block#template-blocks)
 - [ ] [Synced block](https://developers.notion.com/reference/block#synced-block-blocks)
+- [ ] [Meeting notes](https://developers.notion.com/reference/block#meeting-notes) — Notion's AI-meeting block.
+- [ ] [Tab](https://developers.notion.com/reference/block#tab) — Notion's tab block.
+- [ ] [Transcription](https://developers.notion.com/reference/block#transcription) — Notion's AI transcription block.
 
 Missing a block you need? [Open an issue](https://github.com/2anki/server/issues).

web/src/pages/DocsPage/content/cards/templates.md

@@ -0,0 +1,58 @@
+---
+title: Note types and templates
+description: Browse starter Anki note types, preview them, customize, and download.
+---
+
+A note type is Anki's name for the card template — the front layout, the back layout, the CSS, the field list. 2anki ships a handful of starter note types you can drop into Anki as-is, or fork and edit in the browser. The library lives at [2anki.net/templates](https://2anki.net/templates).
+
+**Plan:** Free for browsing, previewing, and downloading. Creating and saving your own templates needs an account.
+
+## When to use this
+
+- You want a better-looking deck than Anki's default white-on-white card.
+- You want a starting point for a custom template — fork one of ours and edit in the browser instead of writing the HTML/CSS from scratch.
+- You want to inspect what fields and styling the n2a-basic, n2a-cloze, n2a-input, or n2a-mcq note types use.
+
+If you just want cards from your notes, you don't have to touch this page — 2anki picks a reasonable default template for every upload. Templates matter once you care about how the cards look.
+
+## Browse the library
+
+Open [2anki.net/templates](https://2anki.net/templates). Three sections show up, in order:
+
+- **Your note types** — anything you've created or customized in the browser (logged-in only).
+- **Official 2anki templates** — handcrafted designs we ship and maintain. Examples: Abhiyan Night Mode, Alexander Deluxe Blue, Only Notion.
+- **Starter note types** — the bare-bones n2a-basic, n2a-cloze, n2a-input, n2a-mcq, and Image Occlusion templates that 2anki uses by default.
+
+Each card has a small preview of the front. Click the card name to open a full-size **Front / Back** preview side-by-side.
+
+## Use a template in Anki
+
+1. Find the template you want. Click the **Download** icon (down arrow) on its card.
+2. The browser downloads a `.apkg` containing one empty deck and the note type.
+3. Open the `.apkg` in Anki to import. The note type becomes available for any new deck.
+4. In Anki, **Add** a card → pick this note type from the **Type** dropdown.
+
+Templates downloaded this way work with Anki on desktop, mobile, and AnkiWeb. You're not locked into 2anki to use them.
+
+## Customize a template
+
+1. Click the **pencil** icon on any template's card. The editor opens at `/templates/edit/<id>`.
+2. Edit the HTML for the front, back, and CSS. The preview updates as you type.
+3. Save. The template lands in **Your note types** at the top of the library.
+4. Download it (the same download icon on its card) and import into Anki.
+
+If you started from one of our templates, your edit is a separate copy — the original stays in the **Official** section.
+
+To make a note type from scratch, click **New note type** in the top right of the library.
+
+## Common mistakes
+
+- **Editing the template doesn't change existing decks.** Anki imports note types by name. If you've already imported a deck that uses `n2a-basic`, customizing your local `n2a-basic` template on 2anki doesn't push back into Anki. Re-export from 2anki, or edit the note type directly in Anki for existing decks.
+- **Deleting an official template.** You can hide it from your view, but the original stays available — drop in another download anytime.
+- **Forgetting to import the .apkg first.** The browser preview is rendered HTML — it's not an `.apkg` until you click download.
+
+## Related
+
+- [Card types](/documentation/cards/card-types) — what kind of card each template produces
+- [Card options](/documentation/cards/card-options) — the per-upload conversion settings
+- [Glossary — Note type](/documentation/reference/glossary) — the term as Anki uses it