Markdown in 30 Minutes

You do not need a special editor or a complete syntax catalog to write useful Markdown. Start with readable plain text. Add a small set of markers for structure, then check both the source and the rendered result.

In 30 minutes, you can create a README.md that explains a project’s purpose, requirements, setup, and first command.

Five-minute Markdown quick start

If another guide sent you here before showing a Markdown example or template, this section is enough to continue. Markdown is readable plain text with a few markers for structure. A filename ending in .md identifies a Markdown file.

Here is a compact example of the source you might see:

# Personal System Charter

## Work to protect

- Course notes
- Project files

Keep the *original files* and record changes in `working-log.md`.

When rendered, the single # becomes the document title, ## becomes a section heading, and each - becomes a list item. The asterisks emphasize “original files,” while backticks mark the filename as literal text. Blank lines separate the heading, list, and paragraph so the structure remains clear.

These are the other markers you may need when using a template:

A shaded example on this site may show Markdown source rather than the final rendered document. Copy the source into the .md file, keep the useful markers, and replace the example wording with your own. You do not need to master the rest of Markdown before completing the template. Continue below when you want the full 30-minute introduction.

Markdown source should remain readable

Markdown is a plain-text format for structured documents. A renderer can turn its markers into HTML or another presentation, but the source should still make sense when no preview is available.

This principle explains most good Markdown:

• use headings to reveal the document’s structure;
• use lists for items that belong together;
• use emphasis only when it clarifies meaning;
• write descriptive link text;
• describe informative images;
• label quoted material; and
• place commands and code where punctuation will not be reinterpreted.

The examples use portable syntax from the CommonMark specification. Some platforms add extensions. Learn the core first.

Start with headings and paragraphs

Use one # for the document title and two ## characters for major sections. Leave a space after the marker.

# Temperature Analysis

This project summarizes one week of recorded temperatures.

## Requirements

Python 3.13 and the files in the `data` folder are required.

## Run the program

Open the project directory and follow the command below.

Blank lines separate paragraphs and blocks. Do not use a heading merely to make text large. A heading names the section that follows.

Keep the hierarchy meaningful. If ## Results is a major section, a subsection inside it can use ### Verification. Avoid skipping levels because a preview style looks better.

Use lists for related items

An unordered list begins each item with -:

The project contains:

- source code in `src`;
- input data in `data`; and
- generated charts in `output`.

An ordered list is appropriate when sequence matters:

1. Open the project folder.
2. Check the requirements.
3. Run the program.
4. Verify the output.

Do not turn unrelated paragraphs into bullets. A list should express a real group or sequence.

Add emphasis sparingly

Use one asterisk for emphasis and two for strong emphasis:

Run the test *after* updating the input file.

**Do not include private student data.**

Emphasis should clarify a distinction or warning. If every sentence is bold, none receives useful emphasis.

Use backticks for short literal text:

Save the file as `README.md` and run `python analyze.py`.

Backticks distinguish filenames, commands, configuration values, and code from the surrounding sentence.

Write links that explain the destination

An inline link places descriptive text in brackets and the destination in parentheses:

Read the [course setup instructions](https://example.edu/course/setup).

Avoid vague text such as “click here.” A reader scanning the page should know where the link leads.

For an image, add ! and write a useful description:

![Line chart of daily high temperatures](output/high-temperatures.png)

The description should communicate the image’s purpose when the image carries information. “Image” or a repeated filename is rarely enough. Also explain important results in nearby text; an image alone should not contain the only answer.

Confirm that local link and image paths are correct relative to the file or follow the rules of the system that will render it.

Mark quotations clearly

Begin a block quotation with >:

> Submit the report and source data before 5:00 p.m.

— CS 101 project instructions

A block quote identifies quoted material; it does not provide a citation by itself. Name or link the source when the context requires attribution.

Use block quotes for actual quotations or clearly labeled callouts, not as a general indentation tool.

Use fenced blocks for commands and code

Place three backticks before and after a block. Add a language label when known:

```python
temperatures = [21.4, 22.0, 19.8]
print(max(temperatures))
```

Use text for output or commands when another language label would mislead:

```text
python analyze.py
```

The fence keeps characters inside the block literal. It does not prove that a command is correct or safe. Read and verify commands before running them.

Build your first README in six passes

Create README.md in a small practice project.

Pass 1: name the project

# Weekly Temperature Summary

Use a specific title rather than Project or README.

Pass 2: state its purpose

This practice project reads seven daily temperatures and reports the minimum,
maximum, and average.

The first paragraph should let a new reader decide whether they have the right project.

Pass 3: list requirements

## Requirements

- Python 3.13
- `data/temperatures.csv`

Name versions only when they matter. Do not invent requirements that you have not tested.

Pass 4: provide the first successful path

## Run the program

From the project directory:

```text
python analyze.py
```

State the required directory and expected result:

The program should print seven records and create
`output/temperature-summary.txt`.

Pass 5: add one useful reference

See the [course data-file instructions](https://example.edu/course/data-files)
before replacing the sample input.

Replace the example address with a real, authoritative destination or omit the link.

Pass 6: add verification

## Verify the result

Open `output/temperature-summary.txt`. Confirm that it contains seven records
and that the maximum matches the largest value in the input file.

Documentation becomes more useful when it tells the reader how to recognize success.

Preview without surrendering the source

Open the file in a Markdown preview. Check:

• one document title is present;
• headings follow a logical hierarchy;
• lists contain the intended items;
• link text and destinations are correct;
• image descriptions are meaningful;
• code fences begin and end correctly; and
• the expected command and output remain readable.

Then return to the source view. If the document is confusing without the preview, simplify it.

Different Markdown systems can render extensions differently. If a course, repository, or publishing system names a specific dialect, test the file there.

Compact syntax reference

Common mistakes

• Choosing syntax by appearance alone. Use structures for their meaning.
• Removing all blank lines. Separate paragraphs and blocks.
• Skipping heading levels. Preserve a logical hierarchy.
• Using raw URLs as link text. Describe the destination.
• Writing weak image descriptions. State what the image communicates.
• Forgetting to close a code fence. Check the rest of the rendered page.
• Documenting an untested command. Run it safely and record verification.
• Using platform extensions without checking support. Prefer the core syntax unless the target system is known.

Do this now

Complete the six passes. Give the README to another person or reopen it after a short break. Follow only its written instructions. Revise any step that depends on memory or unstated context.

Log what you learned

Record only:

• Result: What did the action produce?
• Evidence: What observation, test, or source supports that result?
• Next action or unresolved question: What should happen next?

Next, decide whether Markdown, Word, or PDF fits the job you actually need to do.