Creating decks and cards

1. Before you start

What a deck is

A deck is a named collection of cards. Each card has a Title (list label, spoken first) and Content (main body; Markdown supported). Deck Reader prepares speech audio (M4A) so you can study hands-free — like a playlist of topics.

Free vs Plus (authoring limits)

Import is available on Free within those limits.

Phone, tablet, and Android Automotive

• Phones: portrait; formatting menus above the bottom toolbar; Ω strip above the toolbar; no pinch-zoom on player text.
• Large tablets (10″+): landscape allowed; side Math / Symbols / Colors toolbox; zoom on the editor and player; pinch to zoom player text (80%–300%).
• Android Automotive — parked: simpler library/cards (no create +, no Import toolbar, no per-tile download). Prefer full authoring on phone or tablet.
• Android Automotive — driving: Decks/Cards browse + mini-player; generate/play on decks and cards; prep spinner (tap to stop); Pretty / Markdown editors stay hidden; quieter reminders.

Content selection and scroll

Word select does not stick to markdown glue such as ](deckimg:…). After a drag-scroll, the view keeps your position (no snap to the top of the card).

Pretty mode vs tags

In the card editor, the markdown icon toggles Pretty (formatted preview; images as [Alt: filename] chips) and tags visible (raw source). Turn tags visible when editing [caption] regions — Pretty hides captions entirely because they are audio-only (never shown on the card).

2. How to create a deck

1. Open the Deck library (home screen).
2. Tap + (create) on the bottom toolbar.
3. Enter a deck name → confirm.
4. Tap the new deck to open the card list.

Optional later: rename in library edit mode; turn Auto-generate on the card list so missing audio prepares when you open the deck or save cards; use library Import for .deckreader.csv or ZIP bundles; browse the catalog via Download decks.

Use a clear unique name (import matches by name). When you publish updates, bump Deck Version (MAJOR.MINOR.PATCH) so existing readers can choose Update.

3. How to create a simple card

Goal: plain text only — no Markdown required.

1. Open a deck → card list.
2. Tap + to Add topic (or open a card → Edit).
3. Fill Title (required to save).
4. Fill Content with ordinary paragraphs. Separate ideas with a blank line.
5. Tap Save.

Title: Photosynthesis

Content:
Plants convert light into chemical energy.

They use carbon dioxide and water.
Oxygen is released as a by-product.

Optional: set language/voice on the microphone chips; use deck Auto-generate or the list ↺ to prepare speech. On Free, Content stops at 150 characters while editing.

4. How to create formatted cards (Markdown)

Deck Reader stores Markdown in Title and Content. Delimiters must touch the text (**bold**, not ** bold **). Use the bottom toolbar (Text, Paragraph, Insert, Tables, Ω) or type markup with tags visible.

4.1 Text formatting

Colors: Black, Gray, Brown, Blue, Cyan, Green, Purple, Red, Pink, Orange, Yellow, White. Always close with [/]. Speech reads the inner words only.

Headings: one to eight # at the start of a line, then a space (H1–H6, then B1 / B2 below body size).

4.2 Paragraphs and structure

Multi-paragraph quotes keep > on the blank lines between paragraphs. A blank line without > ends the quote.

> First paragraph.
>
> Second paragraph.

4.3 Inserting elements

Links

• Link → [label](https://example.com)
• Quick link → URL as both label and target
• Same card link → [label](#heading-anchor) from a heading in the same card

How the anchor is derived (prefer Insert so the app fills it): take the visible heading text (after stripping inline markup), trim, lowercase, and replace each whitespace run with -. Punctuation is not stripped. Example: ## Edit mode → #edit-mode; ## Step 1: Setup → #step-1:-setup. If two headings share a slug, the first wins.

Email

• Email → angle-bracket address, e.g. <name@example.com>
• Quick email → bare address, e.g. name@example.com

Images

1. Insert → Image.
2. Pick a file or reuse a deck library image.
3. Optional size in dp: {w:240}, {h:200}, or both.
4. Optional border keys (same meaning as the table style row): t: thickness (1 = 1 dp, 2 = 3 dp; default 1); b: line style (0 = none, 1 = single, 2 = double; default 0 = no frame).

![Sales chart](deckimg:a1b2c3d4e5f67890_chart.png){w:240}
![Framed](deckimg:a1b2c3d4e5f67890_chart.png){w:240; t:2; b:1}

• Multiple images on the same line render side by side; images work in table cells.
• Inside code fences or inline code, image syntax stays literal (not drawn as a bitmap).
• Missing files show a red warning with the full markdown source on the player.
• Speech: reads a short localized image word + alt from the image, then any following [caption] (spoken in audio, hidden on the card — see §4.5).

Symbols (Ω)

Math, symbols, and box-drawing characters. On tablets, the side toolbox inserts the same glyphs quickly.

4.4 Tables

Use the Tables menu (Plus) or type a GFM-style grid:

| Term | Meaning |
| :--- | :--- |
| ATP | Energy currency |
| Chlorophyll | Light-absorbing pigment |

Optional style row before the header (single cell; keys optional, any order; at least one key required):

| {w:100%; wt:80%; t:1; b:1} |

• Column align: :--- / :---: / ---:; optional width digits in the dashes — bare number = characters, trailing % = percent of table width.
• w: phone / compact width — characters (w:200) or percent of content width (w:100%; w:115% scrolls).
• wt: large tablet (≥10″) width — same units as w:. Optional; tablet falls back to w: when omitted.
• t: border thickness — 1 = normal (1 dp), 2 = thick (3 dp). Default 1.
• b: border line style — 0 = none, 1 = single, 2 = double. Default 1.
• Section gap: a body row of dashes only (| -- | or | -- | -- |) draws a visual break — not a data row.
• Continue a cell: end with ^^ then continue that column on the next row.
• [br] starts a visual paragraph in a cell (speech joins with a space; the whole cell is one spoken sentence).
• Wide tables scroll sideways; chevrons stay at the top of the player while the table is on screen.
• With Follow speech on, the player highlights tables row by row as audio plays.
• Table w: / wt: are characters or content %; image {w:} is dp — do not mix the units.

Cell continuation example:

| Steps |
| :--- |
| 1. Make tea ^^ |
| Boil water, then steep 3 min. |
| 2. Serve |

On the card, “Make tea” and “Boil water…” appear in one cell; “2. Serve” is a new row. Use ^^ [br] when you also want a visual paragraph break inside the merged cell.

4.5 Special Deck Reader speech tags

From the Paragraph menu:

• Skip — The section stays visible on the card, but its text is not spoken. Playback announces that a segment was skipped (then a short pause), so the listener knows something was left out.
• Mute — The section stays visible on the card, but its text is not spoken and the app does not announce or pause. Audio continues seamlessly as if that text were never there — useful for teacher notes, spoilers, or on-screen-only hints.
• Caption — The text is hidden on the card (and list tile) but is spoken in audio. Use it to describe a chart, diagram, or image so a listener can follow without looking at the screen — without cluttering the visible card.

![Trend](deckimg:trend-chart.png){w:280}
[caption]The line climbs steadily from left to right.[/caption]

[GREEN]Pass[/] criteria met. [skip]see appendix[/skip] Next topic.
[mute]Teacher note: discuss edge cases here.[/mute] Continue with examples.

Do not confuse image alt text, the Pretty-mode image chip, and [caption] — alt is the short on-card/spoken label; caption is the longer audio-only description. In Pretty mode, caption regions are hidden (tags and text); turn tags visible to edit them.

5. Speech, voices, and preparing audio

1. App default voice — Settings → Configure speech voice.
2. Per-field chips — Title and Content can use different languages/voices (bilingual study).
3. Auto-generate — card list toggle; queues missing audio on deck open / after save.
4. Generate on save — editor top bar when auto-generate is on (skip speech for one save).
5. Manual ↺ — append a card to the shared preparation queue; tap the spinner/ring to remove it.

Preparation uses one global FIFO across decks. In the library, the deck being prepared shows a spinning ring and Preparing audio n/m; waiting decks show a static ring and Queued n cards. Tap the ring → confirm to stop that deck (audio already made is kept). Queue numbers renumber after a stop; re-queued cards get the next (higher) numbers.

Prefer clear sentences; hard line breaks become separate spoken sentences. [br] is visual only. Horizontal rules and box-drawing are silent/omitted in speech. Numbered lists keep stable numbers in speech. On the player, tap a heading link or body block to seek audio to that spoken unit (when M4A + timing exist).

6. Import, export, and deck versions

Export (Plus): Text Only .deckreader.csv, Text + images .deckreader.images.zip, Text + images + audio .deckreader.media.zip, or encrypted Deck Reader Format .deckreader.dkrp (second screen chooses images/audio; text/CSV always included). Legacy .deckreader.pack still imports. ZIP/pack exports include empty media/ and audio/ folders when needed. Written files are verified before the success message.

Import: Library → Import → pick CSV, ZIP, or .dkrp pack. Same deck name (matching is case-insensitive):

• Higher Deck Version → Update (matching titles replaced) or Cancel.
• Same / lower version → Merge (adds cards; colliding different content gets a suffix) or Cancel.

Bump SemVer when you publish an improved deck so readers get the Update path. Creating or renaming to a name that already exists ignoring case is blocked.

7. Tips, escapes, and common pitfalls

Show syntax as literal text

Prefer inline code for examples, or backslash-escape markup characters (\*, \[, \{, …).

Strict pairing

**bold** works; ** bold** does not.

Word wrap

Editor wrap is on by default. Turn it off to scroll wide tables horizontally.

Save vs speech rebuild

Existing audio is kept when spoken text, link targets, and voice settings are unchanged. Joining lines without a period typically rebuilds speech.

Polished-card checklist

1. Clear Title.
2. Structure Content with headings / lists where helpful.
3. Images sized in dp; table widths in characters or % (w: phone, optional wt: tablet).
4. Add [caption] after charts or images that need a longer spoken description (see §4.5).
5. Use [mute] for screen-only notes, or [skip] when the listener should hear that something was omitted.
6. Preview speech chips if bilingual.
7. Save → confirm audio prepares or queue ↺.

8. Quick reference

Toolbar map

Markdown quick guide

**bold**  *italic*  ++underline++  ~~strike~~  `code`
[RED]colored[/]
# H1 … ######## B2
:-  :-:  -:
- bullet    1. numbered
> quote
[label](https://…)   [label](#anchor)   <name@example.com>
![alt](deckimg:file.png){w:240; t:1; b:1}
[skip]…[/skip]  [mute]…[/mute]  [caption]…[/caption]
|{w:100%; wt:80%; t:1; b:1}|
\  escapes the next markup character

9. Creating a deck outside Deck Reader (text editor + ZIP)

You can author on a computer (text editor, spreadsheet, or scripts) and import with Library → Import — the same formats Deck Reader exports.

Choose a format

ZIP layout (CSV + images)

Put these entries at the top level of the ZIP (not inside an extra folder):

Minimal manifest.json (images only, speech later in the app):

{
  "formatVersion": 1,
  "bundleType": "text_only",
  "deckName": "My deck",
  "cardCount": 2,
  "cards": []
}

deck.csv basics

• Save as UTF-8 (UTF-8 with BOM is fine from Excel).
• Line order (top to bottom): (1) deck identity Deck Name,…,Card Count,…; (2) metadata key/value line (export format version 4); (3) header row; (4) one data row per card.
• Header needs at least Title and Content (legacy Definition still imports). Leave optional speech columns blank for app defaults.

Export-shaped template (replace bracketed values; keep labels and fixed numbers as written):

Deck Name,[DECK_NAME],Card Count,[CARD_COUNT]
Export Format Version,4,Policy Version,1,Deck Version,[DECK_VERSION],Issuer Channel,[ISSUER_CHANNEL],Audience Channel,[AUDIENCE_CHANNEL],Export Bundle Type,[BUNDLE_TYPE]
Title,Content,Device,Engine,Title Locale,Content Locale,Title Voice,Content Voice,Title Rate,Title Pitch,Content Rate,Content Pitch,Topic Id
[TITLE],[CONTENT],[DEVICE],[ENGINE],[TITLE_LOCALE],[CONTENT_LOCALE],[TITLE_VOICE],[CONTENT_VOICE],[TITLE_RATE],[TITLE_PITCH],[CONTENT_RATE],[CONTENT_PITCH],[TOPIC_ID]

Editable fields:

Fixed values to leave alone: Export Format Version 4, Policy Version 1, and the exact header column names.

deck.csv example:

Deck Name,Biology Basics,Card Count,2
Export Format Version,4,Policy Version,1,Deck Version,1.0.0,Issuer Channel,"release",Audience Channel,"release",Export Bundle Type,"text_only"
Title,Content,Device,Engine,Title Locale,Content Locale,Title Voice,Content Voice,Title Rate,Title Pitch,Content Rate,Content Pitch,Topic Id
"Photosynthesis","Plants convert light into chemical energy.

They use carbon dioxide and water.",,,,,,,,,,
"ATP","Energy currency of the cell.",,,,,,,,,,

Images

1. Place files under media/ (e.g. media/badge.png).
2. Reference them in markdown: ![Badge](deckimg:badge.png) (optional {w:240} size in dp).
3. Deck Reader rewrites storage names on import. Missing files show a red warning on the player.

Build and import

1. Zip deck.csv, media/ (if any), and manifest.json as {name}.deckreader.images.zip.
2. Copy the file to the device.
3. Deck library → Import → select the CSV or ZIP.

Tip: Export a small deck once from Deck Reader and open the ZIP on your PC — easiest template for manifest.json and media/ naming.

10. Suggestion: HTML → Markdown → deck

If you already have notes as HTML (exports from Docs, Notion, a website, or a personal wiki), a practical pipeline is:

1. HTML → Markdown — use a reputable online converter (or a local tool such as Pandoc) so the body becomes Markdown Deck Reader can store.
2. Clean the Markdown — check headings, lists, links, and tables; replace remote images with files in media/ and deckimg: references; add [caption] for audio-only image descriptions, [mute] for silent screen-only notes, or [skip] when listeners should hear that a section was omitted.
3. Split into cards — one topic per card (clear Title, body in Content). Number titles (01:, 02:, …) if you want alphabetical order to match your outline.
4. Build the CSV or ZIP — as in section 9, then Import into Deck Reader and generate speech.

Online converters vary in quality. Prefer tools that preserve headings and links, then spot-check a few cards in the app before publishing a full deck. Always keep a copy of your original HTML until the import looks right.

This guide matches Deck Reader 2.1.2.x authoring behavior. For exhaustive syntax, see the in-repo Markdown reference.