How to Create an Online Course from a Single Markdown File

Building an online course usually involves a lot of clicking. Create a course. Add a chapter. Add a lesson. Type in the content. Create another chapter. Add another lesson. Repeat forty times.

There's a faster way. If you can create a course from markdown, the entire structure lives in a single file. Three heading levels map directly to course, chapters, and lessons. Write the file, import it, and you're done.

The heading convention

The mapping is simple:

• H1 (# Your Title) becomes the course title
• H2 (## Chapter Name) becomes a chapter
• H3 (### Lesson Name) becomes a lesson inside the most recent chapter
• Everything below an H3 heading becomes that lesson's content

That's it. No special syntax. No proprietary format. Just markdown headings, the same ones you'd use in any text editor, note-taking app, or AI tool.

Any course platform with a markdown importer will parse this structure. Lesso does this natively. You focus entirely on the content. The structural busywork is handled automatically.

A real example

Say you're a fitness coach who wants to create a course on bodyweight training for beginners. Your markdown file would look like this:

# Bodyweight Training for Complete Beginners

## Week 1: Building the Foundation

### Why Bodyweight Training Works
Most people assume you need a gym membership to get strong.
That's not true, and the research backs it up...

### Your First Routine
Start with five exercises. Do each one for 30 seconds
with 15 seconds rest between them...

### Common Mistakes to Avoid
The biggest mistake beginners make is going too hard
in the first week...

## Week 2: Adding Progression

### Understanding Progressive Overload
Your body adapts quickly. If you do the same routine
every day, you'll plateau within two weeks...

### Tempo and Time Under Tension
Slowing down your reps is the simplest way to make
an exercise harder without adding weight...

Import this file and you get a course called "Bodyweight Training for Complete Beginners" with two chapters and five lessons, complete with all the body content.

Where to write your markdown

You don't need a special markdown editor. Any of these work:

Plain text editors. VS Code, Sublime Text, or even Notepad. Save the file with a .md extension.

Note-taking apps. Notion, Obsidian, Bear, and Apple Notes all support markdown or can export to it. If you already take notes in one of these tools, your course outline might already exist.

Google Docs. Write your content with headings (Heading 1, Heading 2, Heading 3) and export as plain text, then add the # symbols. Or copy-paste into a text file and format it.

AI tools. Ask Claude or ChatGPT to structure your content as markdown with H1, H2, and H3 headings. It'll get the format right every time. This is particularly useful when you're converting raw transcripts or notes into course-ready material.

Why markdown changes your workflow

Without markdown import, you build your course inside a web interface, one lesson at a time. That's slow and it breaks your creative flow. You're thinking about content and clicking buttons at the same time.

With markdown, you do all your thinking and writing in whatever tool you're comfortable in. Obsidian, a code editor, a Google Doc, whatever. You focus entirely on the content. Then you import once.

It also means you can version-control your course, keep backups, collaborate with an editor in a shared document, or restructure entire chapters by moving text blocks around before re-importing.

Tips for a clean import

Keep your heading hierarchy consistent. Every lesson (H3) should live inside a chapter (H2). Don't jump from H1 straight to H3.

Put all the body content for a lesson below its H3 heading and before the next heading. Everything between headings belongs to the heading above it.

Use standard markdown formatting within your lesson content. Bold, italics, links, lists, code blocks. Any decent course platform renders all of it.

If your content is long, break lessons into focused topics rather than dumping 3,000 words under a single H3. Shorter lessons have better completion rates.

One file, one import, done

The fastest way to create an online course from markdown is to write one file with three heading levels. H1 for the title. H2 for chapters. H3 for lessons. Import it into your course platform. Your course is structured and ready in minutes, not hours.

If you've been putting off building a course because the platform setup feels tedious, this is the shortcut. Write the content. Let the headings handle the structure.

For the full comparison of text-based course platforms, read The Best Text-Based Course Platform for Writers and Creators. Already have content in another format? See how to convert YouTube scripts, podcast transcripts, or workshop slides into course-ready markdown.