jefftml's HTML & CSS Boilerplate / 2026-html-boilerplate-annotated.html

<!-- The doctype tells the browser "this is modern HTML." It must be the very
     first thing in the file. Without it, browsers fall back to "quirks mode,"
     an old compatibility mode that emulates 1990s bugs. -->
<!DOCTYPE html>

<!-- The root element that wraps everything. lang="en" declares the page is in
     English. Screen readers use this to pick the right pronunciation, and
     browsers use it for translation offers and correct hyphenation. -->
<html lang="en">

<!-- <head> holds information ABOUT the page. Nothing here is drawn on screen. -->
<head>

	<!-- Declares the character encoding: how bytes in the file map to letters.
	     UTF-8 covers essentially every character (é, 中, 🎉). This must appear
	     within the first 1024 bytes of the document, which is why it's first. -->
	<meta charset="UTF-8">

	<!-- The viewport tag, for phones. Without it, mobile browsers pretend the
	     screen is ~980px wide and shrink the whole page down, making text tiny.
	     width=device-width says "use the real screen width."
	     initial-scale=1.0 says "start at 100% zoom, don't shrink anything." -->
	<meta name="viewport" content="width=device-width, initial-scale=1.0">

	<!-- The page title: shown in the browser tab, in bookmarks, and as the
	     clickable headline in search results.
	     &rsquo; is an HTML entity — a code for a character you can't easily type.
	     It produces a curly right single quote (’), the typographically correct
	     apostrophe, rather than the straight typewriter one ('). -->
	<title>jefftml&rsquo;s HTML & CSS Boilerplate</title>

	<!-- The summary search engines often show under the title in results. It has
	     no effect on the visible page or (directly) on ranking. -->
	<meta name="description" content="A 2026 starting point for webpages.">

	<!-- The next line is a commented-out <link> tag. When uncommented, it would
	     load an external file named style.css sitting next to this page.
	     rel="stylesheet" describes the relationship ("this is my styles").
	     href is the path to the file. It's disabled here because the styles are
	     written inline below instead, but when you're ready to move the CSS externally. 
		this helps you get that added quickly. -->
	<!-- <link rel="stylesheet" href="style.css"> -->

	<!-- <style> lets you write CSS directly inside the HTML file. CSS is the
	     language that controls appearance: color, size, spacing, layout. -->
	<style>

		/* :root is a selector that matches the <html> element, but with higher
		   specificity. It's the conventional home for page-wide settings. */
		:root {
			/* Tells the browser this page is happy in both light and dark mode.
			   The browser then supplies sensible default text/background colors
			   matching the visitor's OS setting, and styles form controls,
			   scrollbars, etc. to match. Without this, you'd get black-on-white
			   even for someone who prefers dark mode. */
			color-scheme: light dark;
		}

		/* Styles applied to the <html> element itself. Because every other
		   element lives inside it, font settings here cascade down to the
		   whole page — children inherit them unless told otherwise. */
		html {
			/* Use whatever sans-serif (no little decorative "feet" on letters)
			   font the visitor's system provides. Fast, since nothing downloads. */
			font-family: sans-serif;

			/* Fluid type. Read clamp(MIN, PREFERRED, MAX) as "grow with the
			   screen, but never leave these bounds."
			   - 1rem = the browser's base font size, normally 16px. Using rem
			     rather than px respects a visitor who bumped up their default.
			   - 0.95rem + 0.25vw is the preferred value. 1vw = 1% of the viewport
			     width, so this slice grows as the window widens.
			   - 1.125rem (18px) is the ceiling on huge monitors.
			   Result: ~16px on a phone, smoothly scaling to 18px on a desktop,
			   with no media queries needed. The rem part is essential — a pure
			   vw value would break zooming for people who need it. */
			font-size: clamp(1rem, 0.95rem + 0.25vw, 1.125rem);

			/* Vertical space between lines of text, as a multiple of the font
			   size: each line gets 1.7× its own height. The browser default
			   (~1.2) is cramped for body copy; ~1.5–1.8 reads much better.
			   Deliberately unitless so nested elements compute their own
			   spacing from their own size rather than inheriting a fixed value. */
			line-height: 1.7;

			/* Stops iOS Safari from silently enlarging text when you rotate a
			   phone to landscape. 100% means "don't adjust; I've handled it." */
			-webkit-text-size-adjust: 100%;

			/* Tells the browser to spend a little extra effort on line breaking for
			   body text. Its main job is preventing "orphans" — a last line with a
			   single lonely word dangling on it — by pulling a word down from the
			   line above. It also reduces long runs of hyphenated lines. Purely
			   cosmetic and progressive: browsers that don't support it just wrap
			   normally, and nothing breaks. Applied here on html so it inherits
			   down to every paragraph on the page. */
			text-wrap: pretty;

			/* A typographic nicety: lets opening/closing quotes and some
			   punctuation hang slightly outside the text block so the edge looks
			   optically straight. Supported in Safari today, ignored elsewhere —
			   a harmless progressive enhancement. */
			hanging-punctuation: first last;
		}

		/* Styles for the <main> element defined down in the body. */
		main {
			/* inline-size is the logical version of width. "Inline" means the
			   direction text flows — horizontal in English, but this would
			   automatically mean height in a vertical writing system.
			   min(A, B) picks whichever is smaller.
			   - 68ch: 68 times the width of the "0" character in the current
			     font. Roughly 68 characters per line, near the 45–75 range
			     considered comfortable to read.
			   - 100%: the full width of the parent.
			   So: cap the column at ~68 characters, but on a narrow phone just
			   use the full width instead of overflowing. */
			inline-size: min(68ch, 100%);

			/* Shorthand for margin-left + margin-right (logically, the start and
			   end of the inline direction). auto tells the browser to split the
			   leftover space equally on both sides — this is what centers the
			   column on wide screens. */
			margin-inline: auto;

			/* Shorthand for padding-top + padding-bottom. "Block" is the
			   direction blocks stack — vertical in English. Padding is space
			   INSIDE the element, so this pushes the content away from the very
			   top and bottom edges of the window: 2rem (~32px) of breathing room. */
			padding-block: 2rem;
		}
		
		/* This selector list applies the same rule to all six heading levels;
		   the commas mean "match any of these," not "match them nested." */
		h1, h2, h3, h4, h5, h6 {
			/* "balance" tells the browser to even out the length of each line so
			   a wrapped heading forms a tidy block instead of a long first line
			   with one word stranded underneath. It's a different flavor of the
			   same idea as "text-wrap: pretty;" above — where "pretty" optimizes the ending,
			   "balance" evens out the whole thing. It's used only on headings
			   because browsers cap it at a handful of lines (typically ~4–6) for
			   performance, and because the effect is most visible on short,
			   large text. This overrides the inherited "pretty" for these
			   elements. */
			text-wrap: balance;
		}
	</style>
</head>

<!-- <body> holds everything the visitor actually sees. -->
<body>

	<!-- <main> marks the primary content, as opposed to headers, nav, sidebars,
	     or footers. It's a "semantic" element: it looks like a plain box, but it
	     tells screen readers and search engines what the region means. Screen
	     reader users can jump straight to it. There should be only one per page. -->
	<main>

		<!-- The top-level heading — the page's title as shown to readers.
		     Headings run h1 through h6 and should nest in order (an h3 under an
		     h2 under an h1), forming an outline people can navigate by. Use
		     them for structure, not for making text big; that's CSS's job. -->
		<h1>Header</h1>

		<!-- A paragraph of text. The browser automatically adds space above and
		     below it and wraps the lines to fit. -->
		<p>Paragraph</p>

	<!-- Closing tags, in reverse order of opening. Every nested element must
	     close before its parent does. -->
	</main>
</body>
</html>

1	<!-- The doctype tells the browser "this is modern HTML." It must be the very
2	first thing in the file. Without it, browsers fall back to "quirks mode,"
3	an old compatibility mode that emulates 1990s bugs. -->
4	<!DOCTYPE html>
5
6	<!-- The root element that wraps everything. lang="en" declares the page is in
7	English. Screen readers use this to pick the right pronunciation, and
8	browsers use it for translation offers and correct hyphenation. -->
9	<html lang="en">
10
11	<!-- <head> holds information ABOUT the page. Nothing here is drawn on screen. -->
12	<head>
13
14	<!-- Declares the character encoding: how bytes in the file map to letters.
15	UTF-8 covers essentially every character (é, 中, 🎉). This must appear
16	within the first 1024 bytes of the document, which is why it's first. -->
17	<meta charset="UTF-8">
18
19	<!-- The viewport tag, for phones. Without it, mobile browsers pretend the
20	screen is ~980px wide and shrink the whole page down, making text tiny.
21	width=device-width says "use the real screen width."
22	initial-scale=1.0 says "start at 100% zoom, don't shrink anything." -->
23	<meta name="viewport" content="width=device-width, initial-scale=1.0">
24
25	<!-- The page title: shown in the browser tab, in bookmarks, and as the
26	clickable headline in search results.
27	’ is an HTML entity — a code for a character you can't easily type.
28	It produces a curly right single quote (’), the typographically correct
29	apostrophe, rather than the straight typewriter one ('). -->
30	<title>jefftml’s HTML & CSS Boilerplate</title>
31
32	<!-- The summary search engines often show under the title in results. It has
33	no effect on the visible page or (directly) on ranking. -->
34	<meta name="description" content="A 2026 starting point for webpages.">
35
36	<!-- The next line is a commented-out <link> tag. When uncommented, it would
37	load an external file named style.css sitting next to this page.
38	rel="stylesheet" describes the relationship ("this is my styles").
39	href is the path to the file. It's disabled here because the styles are
40	written inline below instead, but when you're ready to move the CSS externally.
41	this helps you get that added quickly. -->
42	<!-- <link rel="stylesheet" href="style.css"> -->
43
44	<!-- <style> lets you write CSS directly inside the HTML file. CSS is the
45	language that controls appearance: color, size, spacing, layout. -->
46	<style>
47
48	/* :root is a selector that matches the <html> element, but with higher
49	specificity. It's the conventional home for page-wide settings. */
50	:root {
51	/* Tells the browser this page is happy in both light and dark mode.
52	The browser then supplies sensible default text/background colors
53	matching the visitor's OS setting, and styles form controls,
54	scrollbars, etc. to match. Without this, you'd get black-on-white
55	even for someone who prefers dark mode. */
56	color-scheme: light dark;
57	}
58
59	/* Styles applied to the <html> element itself. Because every other
60	element lives inside it, font settings here cascade down to the
61	whole page — children inherit them unless told otherwise. */
62	html {
63	/* Use whatever sans-serif (no little decorative "feet" on letters)
64	font the visitor's system provides. Fast, since nothing downloads. */
65	font-family: sans-serif;
66
67	/* Fluid type. Read clamp(MIN, PREFERRED, MAX) as "grow with the
68	screen, but never leave these bounds."
69	- 1rem = the browser's base font size, normally 16px. Using rem
70	rather than px respects a visitor who bumped up their default.
71	- 0.95rem + 0.25vw is the preferred value. 1vw = 1% of the viewport
72	width, so this slice grows as the window widens.
73	- 1.125rem (18px) is the ceiling on huge monitors.
74	Result: ~16px on a phone, smoothly scaling to 18px on a desktop,
75	with no media queries needed. The rem part is essential — a pure
76	vw value would break zooming for people who need it. */
77	font-size: clamp(1rem, 0.95rem + 0.25vw, 1.125rem);
78
79	/* Vertical space between lines of text, as a multiple of the font
80	size: each line gets 1.7× its own height. The browser default
81	(~1.2) is cramped for body copy; ~1.5–1.8 reads much better.
82	Deliberately unitless so nested elements compute their own
83	spacing from their own size rather than inheriting a fixed value. */
84	line-height: 1.7;
85
86	/* Stops iOS Safari from silently enlarging text when you rotate a
87	phone to landscape. 100% means "don't adjust; I've handled it." */
88	-webkit-text-size-adjust: 100%;
89
90	/* Tells the browser to spend a little extra effort on line breaking for
91	body text. Its main job is preventing "orphans" — a last line with a
92	single lonely word dangling on it — by pulling a word down from the
93	line above. It also reduces long runs of hyphenated lines. Purely
94	cosmetic and progressive: browsers that don't support it just wrap
95	normally, and nothing breaks. Applied here on html so it inherits
96	down to every paragraph on the page. */
97	text-wrap: pretty;
98
99	/* A typographic nicety: lets opening/closing quotes and some
100	punctuation hang slightly outside the text block so the edge looks
101	optically straight. Supported in Safari today, ignored elsewhere —
102	a harmless progressive enhancement. */
103	hanging-punctuation: first last;
104	}
105
106	/* Styles for the <main> element defined down in the body. */
107	main {
108	/* inline-size is the logical version of width. "Inline" means the
109	direction text flows — horizontal in English, but this would
110	automatically mean height in a vertical writing system.
111	min(A, B) picks whichever is smaller.
112	- 68ch: 68 times the width of the "0" character in the current
113	font. Roughly 68 characters per line, near the 45–75 range
114	considered comfortable to read.
115	- 100%: the full width of the parent.
116	So: cap the column at ~68 characters, but on a narrow phone just
117	use the full width instead of overflowing. */
118	inline-size: min(68ch, 100%);
119
120	/* Shorthand for margin-left + margin-right (logically, the start and
121	end of the inline direction). auto tells the browser to split the
122	leftover space equally on both sides — this is what centers the
123	column on wide screens. */
124	margin-inline: auto;
125
126	/* Shorthand for padding-top + padding-bottom. "Block" is the
127	direction blocks stack — vertical in English. Padding is space
128	INSIDE the element, so this pushes the content away from the very
129	top and bottom edges of the window: 2rem (~32px) of breathing room. */
130	padding-block: 2rem;
131	}
132
133	/* This selector list applies the same rule to all six heading levels;
134	the commas mean "match any of these," not "match them nested." */
135	h1, h2, h3, h4, h5, h6 {
136	/* "balance" tells the browser to even out the length of each line so
137	a wrapped heading forms a tidy block instead of a long first line
138	with one word stranded underneath. It's a different flavor of the
139	same idea as "text-wrap: pretty;" above — where "pretty" optimizes the ending,
140	"balance" evens out the whole thing. It's used only on headings
141	because browsers cap it at a handful of lines (typically ~4–6) for
142	performance, and because the effect is most visible on short,
143	large text. This overrides the inherited "pretty" for these
144	elements. */
145	text-wrap: balance;
146	}
147	</style>
148	</head>
149
150	<!-- <body> holds everything the visitor actually sees. -->
151	<body>
152
153	<!-- <main> marks the primary content, as opposed to headers, nav, sidebars,
154	or footers. It's a "semantic" element: it looks like a plain box, but it
155	tells screen readers and search engines what the region means. Screen
156	reader users can jump straight to it. There should be only one per page. -->
157	<main>
158
159	<!-- The top-level heading — the page's title as shown to readers.
160	Headings run h1 through h6 and should nest in order (an h3 under an
161	h2 under an h1), forming an outline people can navigate by. Use
162	them for structure, not for making text big; that's CSS's job. -->
163	<h1>Header</h1>
164
165	<!-- A paragraph of text. The browser automatically adds space above and
166	below it and wraps the lines to fit. -->
167	<p>Paragraph</p>
168
169	<!-- Closing tags, in reverse order of opening. Every nested element must
170	close before its parent does. -->
171	</main>
172	</body>
173	</html>