What Is Markdown? Lightweight Markup Explained

Markdown is a lightweight, plain-text markup language that uses simple symbols to format text into headings, lists, links, and code blocks.

Markdown lets you write formatted documents in plain text using a handful of intuitive symbols. It is the format of README files, GitHub issues and pull request descriptions, and a lot of documentation. Because it is just text, it lives in version control and renders cleanly everywhere - including CI job summaries.

What Markdown is

Markdown uses plain-text conventions to imply formatting: a hash for a heading, asterisks for emphasis, dashes for list items, and backticks for inline code. A renderer turns that text into HTML. The point is that the raw source is still readable even before it is rendered.

Flavors and extensions

There are several dialects. CommonMark is the strict, standardized core, and GitHub Flavored Markdown adds tables, task lists, strikethrough, and fenced code blocks with syntax highlighting. Most tools you meet in CI render GitHub Flavored Markdown.

Why Markdown fits version control

Because Markdown is plain text, diffs are meaningful, merges work, and it does not lock you into a proprietary editor. That makes it the natural format for docs that live next to code and are reviewed in pull requests like any other change.

Markdown in CI job summaries

GitHub Actions lets a job write Markdown to a special summary file, which then renders as a rich report on the run page - tables of test results, links, or a deploy summary. Writing to that file is how you turn raw job output into a readable report without leaving the run.

A Markdown step summary

# Write a Markdown job summary in GitHub Actions
steps:
  - run: |
      echo "## Build report" >> $GITHUB_STEP_SUMMARY
      echo "- Status: passing" >> $GITHUB_STEP_SUMMARY

Latchkey note

The GITHUB_STEP_SUMMARY mechanism is part of the standard runner, so Markdown job summaries render identically on Latchkey managed runners - useful for surfacing build and deploy reports right on the run page.

Key takeaways

Markdown is plain-text markup that uses simple symbols to format headings, lists, links, and code.
GitHub Flavored Markdown adds tables, task lists, and fenced code blocks on top of CommonMark.
In CI you can write Markdown to the job summary file to produce rich, readable run reports.