1 The Problem
We want a converter that reads Markdown (the simple text format with # headings and **bold**) and turns it into HTML a browser can show. It teaches parsing — reading text, recognising patterns, and transforming each piece — the skill behind every format converter and compiler.
Where this shows up: every static-site generator, every README renderer on GitHub, every “rich text” editor, every documentation tool. Reading one format and emitting another is one of the most reusable patterns in software.
2 How to Think About It
Think about how Markdown maps to HTML, before any code:
The plan — in plain English
1. Read the Markdown line by line. → 2. For each line, recognise its type: a line starting with # is a heading; a blank line separates paragraphs; everything else is body text. → 3. Emit the matching HTML tag for each. → 4. Join it all into a finished page.
3 The Build — explained part by part
Here is the complete converter. Each part is explained below.
Pythonmd2html.py
# Convert simple Markdown to HTML.
def convert_line(line):
line = line.rstrip()
if line.startswith("### "):
return f"<h3>{line[4:]}</h3>"
if line.startswith("## "):
return f"<h2>{line[3:]}</h2>"
if line.startswith("# "):
return f"<h1>{line[2:]}</h1>"
if line == "":
return ""
# Replace **bold** with <strong> tags.
while "**" in line:
line = line.replace("**", "<strong>", 1).replace("**", "</strong>", 1)
return f"<p>{line}</p>"
def convert(markdown_text):
lines = markdown_text.split("\n")
html_lines = [convert_line(line) for line in lines]
return "\n".join(html for html in html_lines if html)
if __name__ == "__main__":
sample = "# Hello\nThis is **bold** text.\n## A subheading"
print(convert(sample))
What each part does — in plain words
convert_line(line) — the core: it looks at one line and decides what it is. We check the most specific pattern first (### before ## before # ) because ### also starts with #.line[4:] — slice off the first 4 characters (
“### ”) to keep just the heading text.the while "**" loop — turn each pair of
** into an opening then closing <strong> tag. Replacing one at a time, alternating, pairs them correctly.convert(markdown_text) — split the whole document into lines, convert each, and join the non-empty results into the final HTML.
if __name__ == "__main__": — a sample run so you can see it work immediately. This block only runs when the file is run directly, not when imported by the tests.
Common mistakes — and how to avoid them
✗ Checking
# before ### — then every heading becomes h1, because ### also starts with #.✓ Check the most specific (longest) prefix first.
✗ Forgetting the space in
"# " — then #tag in text is wrongly treated as a heading.✓ Match
"# " with the trailing space, as real Markdown requires.✗ Slicing the wrong number of characters —
line[1:] for "# " leaves a leading space.✓ Slice off the full prefix length, including the space:
line[2:].4 Test & Prove Each Part
We test each Markdown pattern converts to the right HTML — headings, paragraphs, and bold.
A # line becomes an h1 heading
A ## line becomes an h2 heading
Plain text becomes a paragraph
**bold** becomes a strong tag
Pythontest_md2html.py
from md2html import convert_line, convert
def test_h1():
"""# Title becomes an h1."""
assert convert_line("# Title") == "<h1>Title</h1>"
def test_h2():
"""## Sub becomes an h2."""
assert convert_line("## Sub") == "<h2>Sub</h2>"
def test_paragraph():
"""Plain text becomes a paragraph."""
assert convert_line("Hello there") == "<p>Hello there</p>"
def test_bold():
"""**bold** becomes a strong tag."""
assert convert_line("a **b** c") == "<p>a <strong>b</strong> c</p>"
Run with pytest -v. Because convert_line handles one line, each test checks one rule. When parsing, testing each pattern in isolation makes bugs easy to pin down.
5 The Interface
INPUTmarkdown texta string of Markdown
What it expects
# Hello
This is **bold** text.OUTPUThtmlbrowser-ready markup
What it returns
<h1>Hello</h1>
<p>This is <strong>bold</strong> text.</p>6 Run It & Automate It
Run it locally
python3 md2html.pySee the sample convert. Then try feeding it a real
.md file.Jenkins runs the tests automatically — each line explained below.
What you should see when it works
Terminala real run
<h1>Hello</h1>
<p>This is <strong>bold</strong> text.</p>
<h2>A subheading</h2>If it breaks — how to fix it
🚨 All headings come out as h1.
Your checks are in the wrong order. Check
### before ## before #.🚨 Bold text shows the asterisks.
Your
** replacement is not pairing. Replace one at a time, alternating open/close.GroovyJenkinsfile
// Jenkinsfile — automated tests on every change.
pipeline {
agent any
stages {
stage('Get the code') { steps { checkout scm } } // download the code
stage('Install') { steps { sh 'python3 -m venv venv && . venv/bin/activate && pip install pytest' } } // test tool
stage('Test') { steps { sh '. venv/bin/activate && pytest -v' } } // run every test
}
post {
success { echo 'All tests passed.' }
failure { echo 'A test failed — look above.' }
}
}
🎯 Try this next — make it yours
- Italics. Convert
*text*to<em>. (Teaches: another pattern.) - Links. Turn
[text](url)into an anchor. (Teaches: regular expressions.) - Read and write files. Convert a
.mdfile to a.htmlfile. (Teaches: file I/O.)
What you learned
You learned parsing: reading text line by line, recognising patterns, and transforming each into something new — with string slicing and replacement. This is the foundation of every converter and the first step toward a compiler. Related: String Methods, Comprehensions.