Practical course authoring
How to use Markdown for maintainable course authoring
A restrained Markdown convention for course briefs, modules and lessons that keeps educational content portable and easy to revise.
Written by Martin Kruger · Updated 19 July 2026
Direct answer
Use Markdown as the editable source for meaning and structure: headings for sections, lists for true sequences, links for references and fenced blocks only for material that requires them. Keep navigation hierarchy outside the Markdown so content can move without rewriting its heading level.
Treat Markdown as source, not page layout
Markdown is valuable because a person can read it without a renderer and many systems can transform it. That advantage disappears when the file is filled with presentation tricks, raw HTML and tool-specific extensions.
Use the programme tree to represent programme, course, module and lesson relationships. Use Markdown inside each item to structure the explanation that belongs there.
Adopt a small editorial convention
A shared pattern makes lessons easier to scan and revise. It need not force every lesson into one template, but it should settle common decisions such as where outcomes, prerequisites, activities and references appear.
- Start with a direct purpose or learner outcome.
- Use second-level headings for the main sections inside an item.
- Use ordered lists only when order changes the meaning.
- Write descriptive link text and include source context.
- Keep media captions and alternative text beside the media reference.
Write context at every useful level
Programme prose can explain audience and overall method. Course prose can state the capability and prerequisites. Module prose can frame a sequence and connect it to what came before. Lesson prose can carry the actual instruction. This avoids forcing important context into an artificial introductory lesson.
Keep the source portable
Store the Markdown itself in exports, not only rendered HTML. Test ordinary links, code blocks, tables and non-English characters after a round trip. When a platform adds a custom syntax, document it and provide a plain-text fallback so the educational meaning survives migration.