Quick Start

Kx Markdown is a simple text format for creating Practice Sets in Kx Toolbox.

You can start with only a few lines and add richer features when you need them.

1. Start with Practice Lines

The simplest Practice Set content is a list of practice lines:

- Hola.
- Buenos días.
- ¿Cómo estás?
- Muchas gracias.

Each dashed line becomes an individual practice item.

2. Add Practice Set Metadata

Add metadata at the beginning to identify and organize the Practice Set:

[id:basic-greetings]
[cat:greetings, beginner]

- Hola.
- Buenos días.
- ¿Cómo estás?
- Muchas gracias.

The three common metadata fields are:

id:
cat:

id gives it a readable identifier.

cat provides categories for organization.

See Metadata for details.

3. Add Context

Use a context block when the learner would benefit from instructions, background, examples, or other supporting information:

[id:basic-greetings]
[cat:greetings, beginner]

[context]
Practice some common Spanish greetings.
[/context]

- Hola.
- Buenos días.
- ¿Cómo estás?
- Muchas gracias.

Context belongs to the Practice Set as a whole rather than to an individual practice line.

See Context for details.

4. Add Answers

A practice line can include an answer:

- ¿Cómo estás? [ans: "Estoy muy bien."]

A complete Practice Set might now look like:

[id:basic-greetings]
[cat:greetings, beginner]

[context]
Practice some common Spanish greetings.
[/context]

- Hola. [ans: "Buenos días."]
- ¿Cómo estás? [ans: "Estoy muy bien."]
- ¿De dónde eres? [ans: "Soy de México."]
- Gracias. [ans: "De nada."]

See Answers for details.

5. Specify an Answer Language

An answer can explicitly identify its language and voice:

- Buenos días. [ans-en-N: "Good morning."]

Here:

ans-en-N

identifies an English answer using voice N.

Spanish answers can use the same pattern:

- Where is the station? [ans-es-N: "¿Dónde está la estación?"]

See Languages and Voices for details.

6. Request a Translation

Kx Toolbox can generate a translation from the front of a practice line.

An empty thash requests one:

- ¿Dónde está la biblioteca? [thash:]

Without a language suffix, translation defaults to English.

You can also specify the target language:

- ¿Dónde está la biblioteca? [thash-en:]
- Where is the station? [thash-es:]

After translation, Kx Toolbox stores the translated answer and a translation hash.

For example:

- ¿Dónde está la biblioteca? [thash:76e1a039, ans-en-N: "Where is the library?"]

You normally request the translation with an empty thash; Kx Toolbox manages the resulting hash.

See Translation for details.

7. Add Formatting to Context

Context supports a small set of useful formatting features:

[context]
## Greetings

Practice these **common greetings**.

Try to remember the response *before* looking at the answer.

[yellow]Speak each response aloud.[/yellow]
[/context]

Kx Markdown supports headings, bold, italic, highlights, paragraphs, and line breaks in context.

See Formatting for the complete formatting reference.

8. Add Pronunciation Guidance

Vocabulary can include a simple pronunciation guide:

- hola [vocab: "OH-lah", ans: "hello"]
- gracias [vocab: "GRAH-syahs", ans: "thank you"]

Pronunciation guidance is optional.

See Pronunciation for details.

9. Add a Visual When Useful

A practice line can request generated visual content:

- ¿Qué hora es? [visual:clock.01-15]

Visuals can also work with answers:

- ¿Qué hora es? [visual:clock.01-15, ans: "one fifteen"]

See Visuals for the currently documented visual features.

A Useful Starting Practice Set

You do not need every Kx Markdown feature to create a useful Practice Set.

A good starting point is:

[id:basic-spanish-greetings]
[cat:greetings, beginner]

[context]
## Basic Greetings

Practice these common Spanish expressions.

[yellow]Try to respond before viewing the answer.[/yellow]
[/context]

- Hola. [ans-en-N: "Hello."]
- Buenos días. [ans-en-N: "Good morning."]
- ¿Cómo estás? [ans: "Estoy muy bien."]
- ¿De dónde eres? [ans: "Soy de México."]
- Gracias. [ans: "De nada."]

Start small.

Add context, answers, translation, pronunciation, voices, images, or visuals only when they make the Practice Set more useful.

Where to Go Next

For a more detailed introduction, continue with Your First Practice Set.

For the overall structure, see Practice Set Structure.

For a compact syntax summary, see the Practice Set Reference and Line Tag Reference.