# Headings and Paragraphs Course: [Markdown](https://www.devtutorials.ai/learn/markdown) ยท Section: Markdown Fundamentals Source: https://www.devtutorials.ai/learn/markdown/fundamentals/headings-and-paragraphs > Write headings, paragraphs and line breaks that render the way you expect. Fix a release note whose line breaks disappear, learn the six heading levels, force a new line with a backslash, use bold and italic, and see why headings matter to AI agents. ## The Release Note That Fell Apart Ravi writes the release note for version 2.4 of the order-support app. In his editor, every change is on its own line. It looks tidy. He opens it on GitHub. This is what he sees: ```md runnable title="Every line break disappeared" Release 2.4 Fixed refund rounding. Added order search. Faster page load. ``` Look at the Rendered tab. All four lines ran into one paragraph. There is no title. The three changes look like one long sentence. Nothing is broken. This is how Markdown works. One line break inside a paragraph does not start a new line. In this lesson, you will learn the rules that decide where headings, paragraphs and line breaks go. **In simple words:** in Markdown, a blank line separates paragraphs. A single line break does not. ## TL;DR - A **heading** is a line that starts with one to six `#` signs and a space. `#` is the biggest. `######` is the smallest. - A **paragraph** is one or more lines of text. A **blank line** ends it and starts the next one. - A single line break inside a paragraph is ignored. To force a new line, end the line with a backslash `\`. - One star or underscore makes text *italic*. Two make it **bold**. - Headings are the outline of your file. People, renderers and AI agents all use them to find their way. ## A Real-World Example Think about a newspaper page. The big headline tells you the main story. Smaller headlines split it into parts. Under each headline, the text sits in paragraphs. There is a gap between paragraphs, so you can see where one ends and the next begins. Nobody reads a newspaper with no headlines and no gaps. It would be one grey wall of words. Markdown gives you the same three tools: headlines (`#`), paragraphs (blank lines) and emphasis (stars). This lesson covers all three. ## What You Will Learn In this lesson, you will learn: 1. How to write headings, and the six heading levels. 2. Why a heading needs a space after the `#`. 3. How paragraphs and blank lines work. 4. How to force a line break inside a paragraph. 5. How to make text bold and italic, and the traps to avoid. 6. Why headings matter to AI agents. ## Cheat Sheet ```md runnable title="Headings, paragraphs and emphasis" # Release 2.4 ## Fixes Fixed refund rounding. This is a new paragraph, after a blank line. ## Address Order Support Ltd\ 12 Park Road\ Chennai *italic*, **bold** and ***both*** ``` Change the text on the left and watch the right side. Then open the Outline tab: the headings make a small outline. ## Headings ### Six Levels A **heading** is a title for a section. You write it with `#` signs at the start of a line, then a space, then the text. The number of `#` signs sets the **level**. One `#` is level 1, the biggest. Six `#` signs is level 6, the smallest. ```md runnable title="All six heading levels" # Level 1: the page title ## Level 2: a main section ### Level 3: a part of a section #### Level 4 ##### Level 5 ###### Level 6 ``` Open the HTML tab. The renderer turned each line into a heading tag, from `h1` to `h6`. The number in the tag is the number of `#` signs. Most files only need levels 1 to 3. If you reach level 5, the file is usually too deep. Split it into more sections instead. ### When a `#` Is Not a Heading A heading has three rules. The `#` signs come first on the line. There are six or fewer. And there is a space after them. Break any rule and the line stays normal text. ```md runnable title="Three lines that are not headings" #Release notes ####### Seven signs is too many # Four spaces in front makes it code ``` The first line has no space after `#`, so it is a paragraph. The second has seven `#` signs, so it is a paragraph too. The third starts with four spaces, which turns it into a code block. You will learn about code blocks later. Now fix the first line: add a space after `#`. It becomes a heading. "No space after `#`" is the most common heading mistake. Some old apps allowed `#Title`. CommonMark and GitHub do not. Always put a space after the `#` signs. ### One Page Title, Then Steps Down Use **one** level-1 heading per file. It is the title of the whole page. Under it, use level 2 for the main sections and level 3 for parts of a section. Go down one level at a time. Do not jump from level 1 straight to level 4. **Why it matters:** screen readers let blind users jump from heading to heading. A skipped level makes them think a section is missing. AI agents read heading levels the same way, to see which part belongs inside which. ### Heading Links Many renderers give every heading an **anchor**. An anchor is a name you can link to, so a link can jump straight to that heading. GitHub makes the anchor from the heading text. It uses lowercase, drops most punctuation and puts a hyphen for each space. | Heading | Anchor on GitHub | Link to it | |---|---|---| | `## Refund window` | `refund-window` | `[Refund window](#refund-window)` | | `## Install & run` | `install--run` | `[Install](#install--run)` | | `## FAQ` | `faq` | `[FAQ](#faq)` | The second row has two hyphens. The `&` is dropped, but the spaces on both sides of it each become a hyphen. Anchors are added by the renderer. They are not part of CommonMark, so different sites can make them differently. The boxes in this course do not add them. If you rename a heading, every link to its old anchor breaks, so rename carefully. ## Paragraphs ### A Blank Line Makes a New Paragraph A **paragraph** is a block of text. To start a new paragraph, leave one **blank line**: an empty line with nothing on it. ```md runnable title="Lines join, blank lines split" These two lines are one paragraph. This is a second paragraph. It also has two lines. ``` The Rendered tab shows two paragraphs, not four lines. The first two lines joined into one paragraph. The blank line started the second. Open the HTML tab. There are two `p` tags. `p` stands for paragraph. Now fix the release note from the start of the lesson. Add `# ` before the first line, and a blank line after every line. You get a title and three separate lines. ### Why Markdown Joins Lines In Markdown, pressing Enter once inside a paragraph does not usually start a new paragraph. When the Markdown is displayed, the lines are joined with a space. People often wrap long text at 80 characters, or write one sentence per line. A diff then shows exactly which sentence changed. Markdown joins those lines back into one paragraph on the page, so the reader never sees the wrapping. **In simple words:** the line breaks are for the writer. The blank lines are for the reader. ## Line Breaks ### Forcing a New Line Sometimes you want a new line *without* starting a new paragraph. An address is a good example. Each part should be on its own line, but it is still one block. This is called a **hard line break**. There are three ways to make one. ```md runnable title="Three ways to break a line" Backslash at the end of the line: Order Support Ltd\ 12 Park Road\ Chennai Two spaces at the end of the line: Order Support Ltd 12 Park Road Chennai An HTML br tag: Order Support Ltd
12 Park Road
Chennai ``` All three addresses look the same in the Rendered tab. Open the HTML tab: each one has `br` tags. `br` means "line break". ### Which One to Use Use the **backslash**. It is part of CommonMark, and you can see it. The **two spaces** work too, but you cannot see them. Many editors delete spaces at the end of a line when you save. Then the break disappears and nobody knows why. In the box above, the editor shows them as faint dots. The **`br` tag** is HTML, not Markdown. It works on GitHub, but some apps remove HTML for safety. A backslash at the end of the **last** line of a paragraph does not make a break. There is no next line to break to, so the page shows the backslash itself. ## Emphasis ### Bold and Italic **Emphasis** means making words stand out. Markdown has two kinds. - One star or one underscore on each side makes text *italic*. - Two stars or two underscores on each side make text **bold**. - Three stars make text bold *and* italic. ```md runnable title="Bold, italic and both" Refunds take *five* days. Refunds take _five_ days. Refunds take **five** days. Refunds take __five__ days. Refunds take ***five*** days. ``` Open the HTML tab. Italic becomes `em`. Bold becomes `strong`. Stars and underscores give the same result. Most teams pick stars and use them everywhere. Stars work in more places, as the next section shows. ### The Emphasis Traps Emphasis has a few rules that surprise people. ```md runnable title="Where emphasis goes wrong" ** spaces inside the stars ** Call refund*order*total in the script. Call refund_order_total in the script. ``` Look at each line in the Rendered tab. - **Line 1:** nothing is bold. A space right after the opening stars, or right before the closing stars, stops the bold. - **Line 2:** `order` turned italic. Stars inside a word still make emphasis. That is a problem for names like `refund*order*total`. - **Line 3:** nothing changed. Underscores *inside* a word are left alone. That is why names with underscores are safe. To show a name like these exactly, put it in backticks: `` `refund*order*total` ``. You will learn about code in a later lesson. ## Headings Are for Agents Too ### Bold Is Not a Heading Some people make a "heading" by writing a bold line. On the page, it can look almost the same. But it is not a heading. ```md runnable title="A fake heading and a real one" **Refund window** Refunds are allowed within 30 days. ## Damaged items Ask for a photo first. ``` Open the Outline tab. Only "Damaged items" is listed. "Refund window" is just a bold paragraph. An AI agent looking for the refund rule cannot find a section called "Refund window". A screen reader cannot jump to it. A docs site leaves it out of the page menu. **In simple words:** if it is a section title, use `#`. Use bold only for words inside a sentence. ### The Line of Dashes Trap There is a second, older way to write a heading. You put a line of `=` signs or `-` signs under the text. A line of dashes can also create a horizontal divider. However, if the dashes appear directly below text, Markdown may treat that text as a heading. ```md runnable title="The line of dashes trap" Fixed refund rounding. --- Added order search. --- Faster page load. ``` Open the Outline tab. "Fixed refund rounding." became a level-2 heading. The second `---` has a blank line above it, so it stays a divider line. To create a divider, leave a blank line before the dashes. To avoid confusion, use # symbols for headings. ## Where This Is Used - **README files:** the title is `#`, each section is `##`. - **Release notes and changelogs:** one `##` per version. - **Docs sites:** the `##` and `###` headings become the menu on the side of the page. - **AI agent files:** an agent finds rules by their headings, such as `## Commands` or `## Testing`. - **Addresses and poems:** hard line breaks keep each line on its own line. ## Common mistakes | Symptom | Cause | Fix | |---|---|---| | Every line runs into one long paragraph | Single line breaks join lines inside a paragraph | Add a blank line between paragraphs | | `#Title` shows with the `#` sign | No space after the `#` | Write `# Title` | | An address prints on one line | No hard line breaks | End each line except the last with `\` | | A line break vanished after saving | The editor deleted the two trailing spaces | Use a backslash instead of two spaces | | `** text **` shows the stars | Spaces just inside the stars | Write `**text**`, with no inner spaces | | A variable name lost its stars and went italic | Stars inside a word make emphasis | Put the name in backticks | | A normal sentence became a big heading | A `---` line sits right under it | Leave a blank line above the `---` | | A section is missing from the page menu | It is a bold line, not a heading | Use `##` instead of bold | ## Quick Check ## Exercises ## What to Remember - A heading is one to six `#` signs, a space, then the text. Use one `#` per file, then go down one level at a time. - A blank line starts a new paragraph. A single line break does not. - For a new line inside a paragraph, end the line with a backslash `\`. - One star makes *italic*. Two stars make **bold**. No spaces just inside the stars. - Use `#` for section titles, not bold. Only real headings appear in the outline that people, docs sites and AI agents use. ## Further Reading - [CommonMark: ATX headings](https://spec.commonmark.org/0.31.2/#atx-headings): the exact rules for `#` headings. - [CommonMark: hard line breaks](https://spec.commonmark.org/0.31.2/#hard-line-breaks): the backslash and two-space rules. - [GitHub Docs: basic writing and formatting syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax): headings, emphasis and section links on GitHub. Next: **Lists and Nesting**, where you write bullet and numbered lists, nest one list inside another, and repair a setup guide whose lists have collapsed.