A small format. A lasting idea.
Meet Markdown: readable text that can become a structured document.
Read the descriptive transcript
Follow the complete narration and the changes shown in the video. Each example can be copied.
1. Words first. Structure alongside them.
A Markdown file is ordinary text with a few marks that describe its structure. Let's turn this short note into a document.
Source shown
Garden notes
A little room to grow.On screen
The document stays visible while the narration explains the idea.
2. 15 March 2004 / John Gruber introduces Markdown
John Gruber introduced Markdown in March 2004, with contributions from Aaron Swartz. The original purpose was writing readable text for the web.
Source shown
Garden notes
A little room to grow.On screen
The document stays visible while the narration explains the idea.
3. Readable text → HTML → a web page
Instead of filling a draft with HTML tags, writers could use simple marks. A tool would convert the text into HTML for publication.
Source shown
Garden notes
A little room to grow.On screen
The document stays visible while the narration explains the idea.
4. Source on the left. Result on the right.
Here, the left pane holds the source. The right pane renders the same words. The .md filename is a convention for Markdown files.
Source shown
Garden notes
A little room to grow.On screen
The document stays visible while the narration explains the idea.
5. 01 / Put a heading marker before the title
Click before Garden notes. Type a hash character, then a space. Watch the first line become a heading.
Source shown
# Garden notes
A little room to grow.On screen
The cursor moves to the edit point. Each character is inserted or removed in the source, and the preview updates from that text.
6. The marks stay in the source
The preview displays the title without the hash. Your words and their structure remain readable in the source.
Source shown
# Garden notes
A little room to grow.On screen
The document stays visible while the narration explains the idea.
7. 02 / Mark strong emphasis
Now put two asterisks before grow, and two after it. The paired markers give that word strong emphasis.
Source shown
# Garden notes
A little room to **grow**.On screen
The cursor moves to the edit point. Each character is inserted or removed in the source, and the preview updates from that text.
8. Appearance belongs to the renderer
Compare the two panes. The file contains the markers. The renderer chooses how headings and emphasis look.
Source shown
# Garden notes
A little room to **grow**.On screen
The document stays visible while the narration explains the idea.
9. Notes · documentation · AI context
Today, Markdown also appears in notes, project guides, and AI instructions. Structure helps organize that material, but it does not make a claim true.
Source shown
# Garden notes
A little room to **grow**.On screen
The document stays visible while the narration explains the idea.
10. Your turn / Change the title
Pause and write your own title and paragraph below this video. Can you explain which characters are words, and which are formatting markers?
Source shown
# Garden notes
A little room to **grow**.On screen
The document stays visible while the narration explains the idea.
11. Readable text, even without a preview
The hash and space introduce a heading. Paired asterisks mark emphasis. You can still read the document in an ordinary text editor.
Source shown
# Garden notes
A little room to **grow**.On screen
The document stays visible while the narration explains the idea.
Before the preview, there was plain text
Open a Markdown file in a text editor and you see the words together with a few simple marks. # can introduce a heading. Asterisks can mark emphasis. A renderer interprets those marks and displays a structured document. The .md extension is a filename convention; you do not need a special app to read the text.
John Gruber introduced Markdown on 15 March 2004 to help people write for the web using readable plain text that converts to HTML. His original announcement describes a text-to-HTML tool and publishing integrations. Read the original announcement.
Aaron Swartz contributed ideas, design feedback and testing. Gruber also credits plain-text email as a major influence on the syntax. Project description and acknowledgements.
One file, two ways to read it
# Garden notes
A little room to **grow**.The source has a heading and a paragraph. The preview displays their meaning through typography. Font choice, colours and page layout belong to the renderer; they are not stored in those Markdown marks.
A Markdown file is useful for notes, project documentation and other structured writing. GitHub, for example, displays Markdown READMEs as an introduction to a repository. GitHub’s README guide.
Why it appears in AI workflows
Modern tools also read Markdown as context and instructions. That is a newer application of readable text, not Markdown’s original purpose. A heading helps organize your request; it does not prove the content is correct. We will practise a bounded review in the AI lesson.
Try it, then explain it
Change the source below. Afterwards, explain which characters belong to the title itself and which characters tell the renderer that it is a heading. You should be able to read your note without relying on the preview.
YOUR TURN
Make the idea your own.
Write a # title for a note, leave a blank line, then add a short paragraph. Try changing the title and watch the result.
Readable result
A note about the garden
We have room for herbs and a reading bench.
Compare with one possible answer
# Garden notes
We have room for herbs and a reading bench.This is one approach. Your writing can differ while meeting the same structural goal.
TAKE IT WITH YOU
The .md file is ordinary text. A renderer gives its marks a visual form.
Read the editor guide →Progress is stored in this browser. Your practice text is not saved.