|$ curl https://forge-ai.dev/api/markdown?path=docs/html/headings

$cat docs/paragraphs-&-headings.md

updated Today·11 min read·published

Paragraphs & Headings

◆HTML◆Beginner

Introduction

Headings and paragraphs are the backbone of any web page. They provide structure, hierarchy, and readability to text content. Headings break content into sections and tell users (and search engines) what each part of the page is about, while paragraphs deliver the actual readable content.

HTML provides six levels of headings, from <h1> (most important) to <h6> (least important), plus the <p> element for paragraphs. Together they form a semantic content hierarchy that is essential for accessibility and SEO.

Heading Hierarchy

Heading levels define a clear hierarchy from <h1> (top level) down to <h6> (deepest subsection). This hierarchy should mirror the outline of a book: one title (h1), chapters (h2), sections within chapters (h3), and so on.

headings.html

HTML

1	<h1>HTML Documentation Guide</h1>
2	<h2>Getting Started</h2>
3	<h3>Installing a Text Editor</h3>
4	<h3>Creating Your First File</h3>
5	<h2>Core Concepts</h2>
6	<h3>Document Structure</h3>
7	<h3>Elements and Tags</h3>
8	<h4>Block-Level Elements</h4>
9	<h4>Inline Elements</h4>
10	<h3>Attributes</h3>
11	<h4>Global Attributes</h4>
12	<h4>Event Handlers</h4>
13	<h2>Advanced Topics</h2>
14	<h3>Semantic HTML</h3>
15	<h3>Accessibility</h3>

Each heading level represents a nesting depth. Going from <h1> to <h2> to <h3> creates a logical outline. Skipping levels (e.g., jumping from <h1> to <h3>) breaks the hierarchy and confuses screen readers.

✓

best practice

Never skip heading levels. An <h1> should be followed by an <h2>, not an <h3>. Skipping levels creates gaps in the document outline that harm accessibility and SEO. Think of headings as a numbered outline.

Live Heading Preview

The following preview demonstrates a proper heading hierarchy rendered with default browser styles:

preview

Notice how the visual styling reinforces the hierarchy: <h1> is largest and boldest, while each subsequent level decreases in prominence. Screen readers use a similar mental model to help users navigate.

Paragraph Element

The <p> element represents a paragraph of text. It is a block-level element, meaning it starts on a new line and takes up the full width available. Browsers add default margins above and below paragraphs to create visual separation.

paragraphs.html

HTML

1	<p>This is a paragraph of text. Browsers automatically add margins above and below each paragraph to create visual spacing between blocks of text.</p>
2
3	<p>Paragraphs can contain inline elements like <strong>bold text</strong>, <em>italicized text</em>, <a href="#">links</a>, and <span style="color: #00FF41;">styled spans</span>.</p>
4
5	<p>Empty paragraphs should be avoided. Use CSS margin or padding for spacing instead.</p>

Paragraphs should not be nested inside other paragraphs, and they should not contain block-level elements like <div>, other <p> tags, or headings. The HTML parser will automatically close a <p> tag when encountering a nested block-level element.

Line Breaks vs Paragraphs

The <br> element inserts a single line break within a paragraph. It is a void element (no closing tag) and should be used sparingly. Use separate <p> elements for distinct paragraphs, not multiple <br> tags for spacing.

line-breaks.html

HTML

1	<!-- Correct: separate paragraphs -->
2	<p>This is the first paragraph of text. It contains several sentences that form a cohesive idea.</p>
3	<p>This is the second paragraph. Using separate p elements is semantically correct.</p>
4
5	<!-- Acceptable use of br: addresses, poems, code snippets -->
6	<p>
7	John Doe<br>
8	123 Main Street<br>
9	Springfield, IL 62701
10	</p>
11
12	<p>
13	Roses are red,<br>
14	Violets are blue,<br>
15	HTML is fun,<br>
16	And so are you.
17	</p>
18
19	<!-- Incorrect: using br for spacing between paragraphs -->
20	<p>First paragraph text.</p>
21	<br><br>
22	<p>Second paragraph text.</p>

ℹ

info

Use <br> only for line-level content like addresses and poetry. Never use it to create spacing between elements — that is the job of CSS margins and padding. Overusing <br> makes maintenance harder and is semantically meaningless.

Horizontal Rules

The <hr> element represents a thematic break in the content, typically displayed as a horizontal line. It signifies a shift in topic or section within a page:

hr-example.html

HTML

1	<section>
2	<h2>Chapter 1: The Beginning</h2>
3	<p>Content for the first chapter goes here.</p>
4	</section>
5
6	<hr>
7
8	<section>
9	<h2>Chapter 2: The Middle</h2>
10	<p>Content for the second chapter begins after the thematic break.</p>
11	</section>

The <hr> element is semantic, not presentational. It should be used when there is a thematic shift in content, not merely for decorative line separation. For visual-only lines, use CSS borders.

Preformatted Text

The <pre> element displays text exactly as it appears in the HTML source, preserving whitespace, line breaks, and indentation. It is commonly used for code blocks, ASCII art, and any text where formatting matters:

preformatted.html

HTML

1	<pre>
2	function greet(name) {
3	console.log("Hello, " + name + "!");
4	return true;
5	}
6
7	greet("World");
8	</pre>
9
10	<pre>
11	┌─────┬─────┬─────┐
12	│ 1 │ 2 │ 3 │
13	├─────┼─────┼─────┤
14	│ 4 │ 5 │ 6 │
15	├─────┼─────┼─────┤
16	│ 7 │ 8 │ 9 │
17	└─────┴─────┴─────┘
18	</pre>

Text inside <pre> is displayed in a monospace font by default. You can nest <code> inside <pre> to add semantic meaning for code snippets, and you can use CSS to customize the font, colors, and background.

code-block.html

HTML

1	<!-- Best practice for code blocks -->
2	<pre><code>const express = require('express');
3	const app = express();
4
5	app.get('/', (req, res) => {
6	res.send('Hello World');
7	});
8
9	app.listen(3000);</code></pre>

ℹ

info

Always escape HTML entities inside <pre><code> blocks. Replace < with < and > with > to prevent the browser from interpreting them as actual HTML tags.

Blockquotes

The <blockquote> element represents a section of content quoted from another source. Use the cite attribute to reference the source URL:

blockquotes.html

HTML

1	<blockquote cite="https://example.com/source">
2	<p>The best way to predict the future is to create it.</p>
3	<footer>— <cite>Abraham Lincoln</cite>, <a href="https://example.com/source">1864 Address</a></footer>
4	</blockquote>
5
6	<blockquote>
7	<p>HTML is the unifying language of the World Wide Web. It gives structure to content and meaning to text.</p>
8	</blockquote>

For shorter inline quotations, use the <q> element, which automatically adds quotation marks:

inline-quote.html

HTML

1	<p>
2	As Tim Berners-Lee said, <q cite="https://example.com">The Web does not just connect machines, it connects people.</q>
3	</p>

Browsers automatically add the appropriate quotation marks for <q> based on the document language (e.g., curly quotes for English, guillemets for French). The cite attribute on <blockquote> and <q> provides a machine-readable source URL.

Heading Best Practices

Following heading best practices ensures your content is accessible, SEO-friendly, and well-structured:

◆Use exactly one <h1> per page — it represents the page title or main topic

◆Do not skip heading levels — always go h1 → h2 → h3 → h4 in order

◆Use headings to describe the content that follows, not for visual styling

◆Keep heading text concise and descriptive — avoid vague headings like 'More' or 'Click Here'

◆Nest sections correctly: an <h2> introduces a new major section, <h3> is a subsection

◆Use CSS for font sizing — do not choose a heading level based on its default visual size

◆Ensure heading text makes sense out of context (e.g., for screen reader navigation menus)

◆Avoid empty headings or headings that contain only images without alt text

◆Use <h1> through <h6> in order — you can use all six levels if needed

◆Test your heading structure with a tool like the WAVE evaluation tool or heading map extension

✓

best practice

Screen reader users navigate web pages by jumping between headings. A logical heading hierarchy is one of the most impactful accessibility improvements you can make. Test by navigating your page using only the Tab key and heading shortcuts (H key in VoiceOver, NVDA, and JAWS).

Semantic Structure

Combining headings with semantic HTML elements creates a rich, meaningful document structure. Use <section>, <article>, <nav>, and <aside> to group related content:

semantic-structure.html

HTML

1	<article>
2	<h1>How to Write Semantic HTML</h1>
3	<p>Semantic HTML means using the correct elements for their intended purpose.</p>
4
5	<section>
6	<h2>Why Semantics Matter</h2>
7	<p>Semantic HTML improves accessibility, SEO, and maintainability.</p>
8
9	<section>
10	<h3>Accessibility Benefits</h3>
11	<p>Screen readers use semantic elements to provide navigation.</p>
12	</section>
13
14	<section>
15	<h3>SEO Benefits</h3>
16	<p>Search engines use heading structure to understand page content.</p>
17	</section>
18	</section>
19
20	<section>
21	<h2>Common Semantic Elements</h2>
22	<ul>
23	<li><header> — introductory content</li>
24	<li><main> — primary content</li>
25	<li><footer> — closing content</li>
26	<li><nav> — navigation links</li>
27	</ul>
28	</section>
29	</article>

Each <section> should ideally have its own heading. The <article> element represents a self-contained composition that can be independently distributed or reused, such as a blog post, news story, or forum comment.

🔥

pro tip

Use the HTML5 Outliner (a browser extension) or the W3C Nu HTML Checker to verify your document outline. A well-structured page should read like a coherent table of contents when all headings are extracted.

Common Mistakes

✗ Skipping Heading Levels

<h1>Page Title</h1><h3>Subsection</h3>

Jumping from h1 to h3 breaks the document outline and confuses screen readers.

✓ Correct Hierarchy

<h1>Page Title</h1><h2>Subsection</h2><h3>Sub-subsection</h3>

Always maintain sequential heading order for proper accessibility.

✗ Using <br> for Paragraph Spacing

<p>First paragraph.</p><br><br><p>Second paragraph.</p>

Use CSS margins on p elements instead of empty br tags.

✓ Correct Spacing

<p class="mb-4">First paragraph.</p><p class="mb-4">Second paragraph.</p>

Use CSS for spacing between paragraphs. Every br is semantically meaningless.

✗ Multiple <h1> Elements

<h1>Section 1</h1><h1>Section 2</h1><h1>Section 3</h1>

Multiple h1 elements dilute the page hierarchy. Use one h1 and nest h2, h3, etc.

✓ Single h1

<h1>Page Title</h1><h2>Section 1</h2><h2>Section 2</h2>

One h1 establishes the main topic; all other headings nest below it.

Best Practices

◆Use one <h1> per page that describes the page's main topic

◆Maintain a logical heading hierarchy without skipping levels

◆Keep heading text concise, descriptive, and unique within the page

◆Use <p> for paragraphs, not <div> or <br> for spacing

◆Prefer <ul> or <ol> for lists instead of manual <br> separated items

◆Use <blockquote> for extended quotations and <q> for inline quotes

◆Add <cite> and <footer> inside blockquotes for attribution

◆Use <pre><code> for code examples to preserve formatting

◆Combine headings with semantic sectioning elements for structure

◆Validate your heading outline using accessibility tools

Browser Support

Element	Chrome	Firefox	Safari	Edge
h1–h6	✓	✓	✓	✓
p	✓	✓	✓	✓
br	✓	✓	✓	✓
hr	✓	✓	✓	✓
pre	✓	✓	✓	✓
blockquote	✓	✓	✓	✓

$Blueprint — Engineering Documentation·Section ID: HTML-15·Revision: 1.0

X GitHub YouTube Instagram Facebook Buy me a coffee Sponsor