Format Spec

Flashdown Format

A minimal markup format for flashcard content. Markdown-compatible and purpose-built for cards.

The Problem

Most apps store cards as plain text or HTML blobs. The app doesn't know what's a word, what's a definition, what's an example. It's all just... text. You end up with walls of content where nothing stands out.

Our Approach

Use standard Markdown syntax with semantic meaning for flashcards. A heading is the main content. A blockquote is secondary info. No custom syntax to learn—just Markdown with purpose.

Our belief: The best format is one you can understand in 30 seconds, edit in any text editor, and trust to look good everywhere.

Why It Matters

Visual hierarchy isn't decoration—it's cognition. The main word should feel like the main word. Examples should look like examples. Content that knows what it is, displayed as what it means.

Live Preview

Try editing the flashdown code below and see the card preview update in real-time.

Flashdown
Card Preview
ephemeral
/ɪˈfem(ə)rəl/ • adjective
Lasting for a very short time
The ephemeral nature of fashion trends
Morning dew is ephemeral, gone by noon
From Greek ephēmeros "lasting only a day"

Syntax Reference

Block Types

Flashdown uses standard Markdown prefixes with semantic meaning for cards.

PrefixTypePurposeDisplay
# mainPrimary content (word, question)Large, bold, centered
> subSecondary info (pronunciation)Smaller, muted
(none)detailDefinition, explanationNormal size, readable
@ exampleUsage exampleItalic, indented
>> noteExtra info, mnemonicSmall, subtle
![](url)imageEmbedded imageCentered image

Inline Formatting

SyntaxRenders as
**text**text
*text*text
__text__text
[text](url)text
漢字[かな]漢字(かな) (furigana)

Design Goals

Markdown Compatible

Uses standard Markdown syntax (#, >, !, []) so you already know how to write it.

Visual Hierarchy

Clear main/sub distinction. Each block type has semantic meaning for proper display.

Japanese Support

Native furigana notation with 漢字[かな] syntax for Japanese vocabulary cards.

Lossless Import

AI converts Anki templates to Flashdown, preserving structure and meaning.

Why Flashdown?

vs Anki Templates

Anki templates require Mustache + HTML + CSS. Flashdown uses familiar Markdown syntax with automatic styling.

Anki Template
<div class="word">{{Word}}</div>
{{#Pronunciation}}
  <div class="pron">{{Pronunciation}}</div>
{{/Pronunciation}}
<div class="def">{{Definition}}</div>
{{#Example}}
  <div class="ex">{{Example}}</div>
{{/Example}}

/* Plus CSS file... */
.word { font-size: 24px; }
.pron { color: #666; }
.ex { font-style: italic; }

Requires template + fields + CSS. Complex to maintain.

Flashdown
# ephemeral
> /ɪˈfem(ə)rəl/ • adjective
Lasting for a very short time
@ The **ephemeral** nature of fashion
>> Greek: ephēmeros

Standard Markdown syntax. Styling handled automatically.

vs JSON

JSON is harder to read and edit by hand. Flashdown is human-friendly while still being structured and parseable.

JSON
{
  "main": "ephemeral",
  "sub": "/ɪˈfem(ə)rəl/ • adjective",
  "details": [
    "Lasting for a very short time"
  ],
  "examples": [
    "The ephemeral nature of fashion"
  ],
  "notes": ["Greek: ephēmeros"]
}

Verbose, hard to scan, easy to mess up quotes/brackets

Flashdown
# ephemeral
> /ɪˈfem(ə)rəl/ • adjective
Lasting for a very short time
@ The **ephemeral** nature of fashion
>> Greek: ephēmeros

Compact, readable, easy to edit in any text editor

vs Raw Markdown

Standard Markdown lacks semantic meaning for cards. Flashdown prefixes carry card-specific semantics while staying Markdown-compatible.

Standard Markdown
# ephemeral
*/ɪˈfem(ə)rəl/ • adjective*

Lasting for a very short time

> The **ephemeral** nature of fashion

*Greek: ephēmeros*

Is # a heading or the main word? Is > a quote or an example?

Flashdown
# ephemeral
> /ɪˈfem(ə)rəl/ • adjective
Lasting for a very short time
@ The **ephemeral** nature of fashion
>> Greek: ephēmeros

# = main word, > = pronunciation, @ = example, >> = note