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.

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 them entirely.

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

Email

• Email → <name@example.com>
• Quick email → bare address

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; optional border keys.

![Sales chart](deckimg:a1b2c3d4e5f67890_chart.png){w:240}

• 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: localized image word + alt, then optional [caption].

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 |

• Column align: :--- / :---: / ---:; optional width % digits in the dashes.
• Optional style row before the header: |{w:200; t:1; b:1}| (width in characters).
• Continue a cell: end with ^^ then continue on the next row.
• [br] starts a visual paragraph in a cell (speech joins with a space).
• Table w: is characters; image {w:} is dp — do not mix the units.

4.5 Special Deck Reader speech tags

From the Paragraph menu:

• Skip — omit a section but tell the listener something was skipped.
• Mute — teacher notes or spoilers on screen only; seamless audio.
• Caption — describe a chart or image in speech without cluttering the 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.

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 ↺ — queue or refresh; tap the spinner/ring to remove from the queue.

Prefer clear sentences; hard line breaks become separate spoken sentences. [br] is visual only. Horizontal rules and box-drawing are silent/omitted in speech.

6. Import, export, and deck versions

Export (Plus): text-only .deckreader.csv, text + images .deckreader.images.zip, or text + images + M4A .deckreader.media.zip.

Import: Library → Import → pick CSV or ZIP. Same deck name:

• 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.

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.
4. Captions for charts via [caption].
5. Mute or skip teacher-only notes.
6. Preview speech chips if bilingual.
7. Save → confirm audio prepares or queue ↺.

8. Quick reference

Toolbar map

Markup cheat sheet

**bold**  *italic*  ++underline++  ~~strike~~  `code`
[RED]colored[/]
# H1 … ######## B2
:-  :-:  -:
- bullet    1. numbered
> quote
[label](https://…)   [label](#anchor)   <a@b.c>
![alt](deckimg:file.png){w:240}
[skip]…[/skip]  [mute]…[/mute]  [caption]…[/caption]
\  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).
• Include metadata lines when possible (Deck Version as MAJOR.MINOR.PATCH). Missing version is treated as 1.0.0.
• Header row needs at least Title and Content (legacy Definition still imports).
• Optional locale / voice / rate / pitch columns — leave blank for app defaults.

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 — that is the easiest template for naming and metadata.

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 [skip] / [mute] / [caption] where useful.
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.