---
name: coursetag
description: Write a complete e-learning course as a CourseTag document (.docx) — tagged plain text that imports into CourseConverter or any CourseTag implementation and becomes an interactive SCORM/HTML course. Use when asked to create, draft, or convert material into a course, training module, induction, compliance training, or CourseTag/SCORM-ready document.
---

# Writing CourseTag courses

CourseTag is an open standard (v1.0, coursetag.org) for authoring courses as ordinary
documents. Plain text carries the words; bracketed tags carry the learning structure.
A CourseTag document imports into CourseConverter — the reference implementation — and
becomes an interactive course that exports to SCORM 1.2 or HTML.

Your job is to produce a **valid, well-structured .docx** the author can import and then
edit by hand. You are writing a first draft in a format they already know how to change —
not a finished artefact they must accept.

## Deliverable

A `.docx` file. Not a SCORM package, not HTML, not a chat message of tagged text.

The author imports it into CourseConverter (or another CourseTag tool), refines it in the
editor, and exports the course. Say so in one line when you hand the file over.

## Workflow

1. **Establish the brief.** Topic, audience, jurisdiction, length, and whether it is
   compliance training (which changes the ending — see Confirmation). If the user supplied
   source material, that material's facts win over your own knowledge; keep their facts and
   improve the structure.
2. **Outline first.** List the modules and what each one must achieve, and show the user
   before writing the body. A 10-module course is a lot of wasted words if the shape is wrong.
3. **Write the tagged text** to a plain `.txt` file, following Structure and Authoring rules
   below.
4. **Validate** with the checklist. Tag errors are silent — a malformed block imports as
   stray text, not an error message.
5. **Build the .docx** with the script below, and deliver the file.

## Structure

```
# Module title              → Heading 1. Starts a new module.
## Lesson title             → Heading 2. A sub-heading inside the module.
Ordinary paragraph text     → a rich text block.
- bullet item               → bulleted list (preserved on import).
1. numbered item            → numbered list (preserved on import).
[tag] ... [/tag]            → a structured, interactive block.
```

Untagged headings and paragraphs import as-is. Reach for a tag only when you want an
interactive block. Tags are case-insensitive. Never nest one tag inside another.

A `[section_break]` is a numbered section marker **within** a module, not a module boundary
— `# Heading 1` is what starts a module.

## The tags

### Callout — highlighted note
Variants: `info`, `warning`, `success`, `tip`. No variant means a plain note.
```
[callout warning]
Report a suspected incident immediately. Nobody has been disciplined for reporting quickly.
[/callout]
```

### MCQ — knowledge check
A **leading asterisk** marks the correct option. Exactly one correct option.
`Question:` and `Explanation:` are literal line prefixes.
```
[mcq]
Question: An email from your CEO's correct address asks you to urgently pay an invoice to a new account. What should you do first?
A: Pay it — the address is correct, so the request is legitimate
*B: Verify the request through a separate channel, such as phoning them
C: Reply to the email asking whether it's genuine
Explanation: A correct sender address proves little — accounts get compromised and addresses can be spoofed. Replying reaches the same account, so it confirms nothing.
[/mcq]
```
Optional background image: `[mcq bg=https://example.com/image.jpg]`

### Accordion — expandable rows
One per line, `heading :: body`.
```
[accordion]
Urgency :: Anything demanding action within hours. Real processes rarely collapse if you take ten minutes to verify.
An unexpected request :: A supplier changing bank details, or a colleague asking for gift cards.
[/accordion]
```

### Flip cards — two-sided cards
One per line, `front :: back`. Optional images after both text sides:
`front :: back :: frontImageUrl :: backImageUrl`.
```
[flipcards]
Phishing :: A mass email designed to trick anyone who receives it
Spear phishing :: A targeted version, using details about you specifically
[/flipcards]
```

### Tabs — tabbed panels
One per line, `label :: body`.
```
[tabs]
Good :: A unique passphrase per account, in a password manager, with MFA enabled
Dangerous :: One password everywhere, no second factor, written on a note by the monitor
[/tabs]
```

### Matching — drag-to-match
First line **without** `::` is the instruction. Then 2–8 pairs, `item :: prompt`.
```
[matching]
Match each practice to why it matters
Use a password manager :: Removes the need to reuse passwords across sites
Turn on multi-factor authentication :: Means a stolen password alone isn't enough
[/matching]
```

### Process — sequential steps
One per line, `title :: description`.
```
[process]
Stop :: Don't click anything else, and don't delete the email — it's evidence
Report :: Contact IT immediately by phone, not email
[/process]
```

### Confirmation — attestation checkbox
Blocking by default; `[confirmation optional]` makes it non-blocking.
```
[confirmation]
I have read and understood this training, and I know how to report a suspected incident.
[/confirmation]
```

### Quote — pull quote
Attribution after an em dash, inside the block.
```
[quote]
Amateurs hack systems, professionals hack people. — Bruce Schneier
[/quote]
```

### Hotspot — clickable markers on an image
URL and alt in the opening tag. Each marker: `label :: x :: y :: tooltip :: body`,
where x and y are percentages (0–100) of image width and height.
```
[hotspot url=https://example.com/panel.png alt=Control panel layout]
Emergency stop :: 30 :: 25 :: Press to halt all motion :: Hold for two seconds until the indicator turns red
[/hotspot]
```
Coordinates are far easier to set by dragging in the editor — prefer an empty
`[hotspot][/hotspot]` unless you know the image.

### Image and stock image
```
[image url=https://example.com/photo.jpg alt=Description caption=Optional caption]
[stock: warehouse safety signage]
```
`[stock: keyword]` fetches a matching image from Pixabay automatically. **Use it whenever
you don't have a real URL** — never invent an image URL. Images embedded directly in the
document import automatically with no tag.

### Video
```
[video]
https://www.youtube.com/watch?v=VIDEO_ID
[/video]
```
Only with a URL the user supplied.

### Section break and divider
```
[section_break]
1 :: Why this matters
[/section_break]

[divider]
```

### Blank blocks
Any tag left empty creates a blank block of that type, ready to fill in the editor:
`[mcq][/mcq]`, `[matching][/matching]`, `[hotspot][/hotspot]`.

Use these deliberately — to sketch a skeleton the author will complete, or where content
needs a human (real photos, site-specific procedures, local emergency contacts). Don't use
them to avoid writing.

## Authoring rules

**Interaction, not just prose.** Every module gets at least one interactive block and ends
with an `[mcq]`. A module of unbroken paragraphs is a document, not a course.

**Vary the blocks.** Never two of the same type in a row. Match the block to the content:
sequence → `[process]`; terms → `[flipcards]`; objections or FAQs → `[accordion]`;
comparison → `[tabs]`; relationships → `[matching]`.

**MCQs must be answerable only by someone who understood.** Distractors should be
plausible — the mistake a real learner would actually make — never filler. The
`Explanation:` line teaches why the wrong answers are wrong; it doesn't restate the right one.

**One idea per block.** Three short paragraphs beat one long one. Learners scan.

**Compliance training ends with a `[confirmation]`** whose wording states what the learner
is attesting to in specific terms, not "I have read the above".

**Write in the user's variety of English** and use their jurisdiction's regulators,
legislation and figures. Don't import American examples into an Australian course.

**Cite real sources or say nothing.** Statistics need a named source and year. Never invent
a figure, a regulation, a clause number or a URL. If a fact matters and you're unsure of it,
leave a `[callout info]` flagging it for the author to confirm.

**No markdown inside tag blocks.** No `**bold**`, no `#`, no `|` tables. Bold and italic
work in ordinary paragraphs only.

## Validation checklist

Run through every item before building the .docx. These failures import silently as stray
text — there is no error message.

- Every opening tag has a matching `[/tag]`, spelled identically
- No tag is nested inside another tag
- Every `[mcq]` has exactly one option with a **leading** asterisk (`*B:`, never `B*:` or `*B)`)
- Every `[mcq]` has a `Question:` line and an `Explanation:` line
- Pair blocks use ` :: ` as the separator — never `-`, `|`, `=` or a colon
- `[matching]` has 2–8 pairs, and its first line has no `::`
- `[hotspot]` markers have exactly five `::`-separated fields, with x and y between 0 and 100
- Callout variants are only `info`, `warning`, `success` or `tip`
- No invented URLs anywhere — `[stock: keyword]` instead
- Module titles are `# Heading 1`; nothing else uses `#`

## Building the .docx

Write the tagged text to `course.txt`, then run this. It maps `#`/`##` to Word heading
styles and writes every other line verbatim, so bracket tags and leading asterisks survive
untouched (a markdown converter would mangle them).

```python
# build_docx.py — usage: python3 build_docx.py course.txt course.docx
import sys, re
from docx import Document

src, out = sys.argv[1], sys.argv[2]
doc = Document()
for raw in open(src, encoding="utf-8").read().split("\n"):
    line = raw.rstrip()
    if not line.strip():
        continue
    if line.startswith("## "):
        doc.add_paragraph(line[3:].strip(), style="Heading 2")
    elif line.startswith("# "):
        doc.add_paragraph(line[2:].strip(), style="Heading 1")
    elif line.startswith("- "):
        doc.add_paragraph(line[2:].strip(), style="List Bullet")
    elif re.match(r"^\d+\.\s", line):
        doc.add_paragraph(re.sub(r"^\d+\.\s", "", line), style="List Number")
    else:
        doc.add_paragraph(line)
doc.save(out)
print(f"wrote {out}")
```

Needs `python-docx` (`pip install python-docx`). If it can't be installed, deliver the
`.txt` and tell the author to paste it into Word, applying Heading 1 to module titles.

## Handing it over

Deliver the `.docx` with one line of context: what the course covers, how many modules, and
that importing it into CourseConverter turns the tags into interactive blocks that can be
edited and exported to SCORM or HTML.

Flag anything the author must check before publishing — statistics to verify, blank blocks
to fill, site-specific procedures or emergency contacts you couldn't know.
