Markdown Is Source, HTML Is Output

You already built HTML directly.

Now Jekyll gets useful.

Markdown lets you write content with less markup, while Jekyll turns that source into HTML during the build.

Create a Markdown page

Add about.md:

# About Me

I build things because I like seeing how systems fit together.

## Current interests

- robotics
- programming
- cybersecurity

Build the site.

Inspect the generated result in _site.

The browser does not receive Markdown syntax such as # About Me. Jekyll's Markdown processor turns it into HTML such as a heading element.

Source and output are different representations

about.md
   ↓ Markdown rendering
Jekyll
   ↓
_site/about.html

Open both files side by side.

Ask:

• Which one is easier to author?
• Which one does the browser need?
• Which one should you edit?
• What transformation can you prove happened?

Guided experiment

Add:

**Important:** this sentence should be bold.

Before building, predict the HTML element you expect.

Then build and inspect _site/about.html.

Do not settle for "it looks bold." Find the generated markup.

When Markdown is a poor fit

Markdown is excellent for prose, headings, lists, links, and simple content structure.

Sometimes you need precise HTML structure. Jekyll allows HTML pages too.

The choice is not:

Markdown good, HTML bad.

The better question is:

Which representation makes this source easiest to maintain while still producing the output I need?

Portfolio action

Move your About content into about.md.

Keep the source simple. Styling comes later.

Checkpoint

Submit or save:

Markdown source line:
Generated HTML line:
Transformation I observed:
Why I would edit the source instead of the generated HTML: