Skip to content

Commit 25032bc

Browse files
Schalk NeethlingSchalk Neethling
authored andcommitted
feat: add introduction
1 parent a0d86c2 commit 25032bc

7 files changed

Lines changed: 95 additions & 18 deletions

File tree

.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,4 +21,4 @@ pnpm-debug.log*
2121
.DS_Store
2222

2323
# agent files
24-
src/content/AGENTS.md
24+
AGENTS.md

.prettierrc.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{}

astro.config.mjs

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,12 @@ export default defineConfig({
1414
label: "Chapters",
1515
items: [
1616
// Each item here is one entry in the navigation menu.
17-
{ label: "Chapter 1", link: "/book/chapter001/" },
18-
{ label: "Chapter 2", link: "/book/chapter002/" },
17+
{ label: "Introduction", link: "/book/introduction/" },
18+
{
19+
label: "Getting started with HTML",
20+
link: "/book/chapter001/",
21+
},
22+
{ label: "The link element", link: "/book/chapter002/" },
1923
],
2024
},
2125
],

src/content/docs/book/chapter001/index.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "Chapter 1: Getting started with HTML"
3-
keywords: html, html standard, how-to, learn html
4-
description: Learn the elements of the core, semantic language of the web.
3+
keywords: html document structure, html elements, html head, html title, html base, doctype, html lang attribute, html metadata, web accessibility, html semantics, html document root, html getting started
4+
description: Master the fundamental HTML document structure. Learn about the html, head, title, and base elements, DOCTYPE declarations, and essential attributes for web accessibility and SEO.
55
---
66

77
If one has always thought of HTML as just some form elements, div and span elements, links and paragraph tags, it seems strange that one would dedicate an entire book to the language. As you will see throughout this book, there is a **lot** more to the HTML language.

src/content/docs/book/chapter002/index.md

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: "Chapter 2: The link element"
3-
keywords: html, html standard, how-to, learn html, link element, link, stylesheet, resource hints, dns-prefetch, preconnect, prefetch, prerender, preload, stylesheet, icon, manifest, pingback, prerender, prefetch, dns-prefetch, preconnect, preload, stylesheet, icon, manifest, pingback
4-
description: Learn the HTML link element, its attributes, resource hints, and other uses.
3+
keywords: html link element, link rel attribute, link href attribute, link media attribute, stylesheet linking, favicon icon, resource hints, dns-prefetch, preconnect, prefetch, preload, modulepreload, html performance optimization, web performance, link crossorigin, alternate stylesheet, search link, pingback
4+
description: Master the HTML link element and its powerful attributes. Learn stylesheet linking, favicon implementation, resource hints for performance optimization, and advanced techniques like preconnect, prefetch, and modulepreload.
55
---
66

77
Chapter two covers the `link` element, its attributes, and use cases. The `link` element connects documents and resources. You may know it primarily for linking stylesheets, but it does much more. We start with well-known attributes and move to newer, lesser-known ones.
@@ -11,16 +11,16 @@ Chapter two covers the `link` element, its attributes, and use cases. The `link`
1111
The `href` attribute is the core of this element. It is required (unless `imagesrcset` is present) and must contain a valid uniform resource locator (URL). The most common use case is linking an external stylesheet:
1212

1313
```html
14-
<link href="style/main.css">
14+
<link href="style/main.css" />
1515
```
1616

1717
## The `media` attribute
1818

1919
This attribute was primarily used to link separate stylesheets for screen or print rendering. For example:
2020

2121
```html
22-
<link rel="stylesheet" href="screen.css" media="screen">
23-
<link rel="stylesheet" href="print.css" media="print">
22+
<link rel="stylesheet" href="screen.css" media="screen" />
23+
<link rel="stylesheet" href="print.css" media="print" />
2424
```
2525

2626
Since CSS added media queries, developers commonly use `@media print` in stylesheets for print styling. However, separating print rules into a dedicated stylesheet has benefits. When viewing on a display, the browser marks print stylesheets as low-priority. It defers downloading and parsing until screen resources are complete. When the browser downloads print stylesheets it does so in a non-blocking manner.
@@ -34,7 +34,7 @@ Besides the common values `all`, `screen`, and `print`, the `media` attribute su
3434
rel="stylesheet"
3535
href="tablet.css"
3636
media="screen and (width >= 48rem) and (width < 64rem)"
37-
>
37+
/>
3838
```
3939

4040
> **Note:** There are also around [8 more media types, which have been deprecated](https://drafts.csswg.org/mediaqueries/#media-types).
@@ -50,7 +50,7 @@ What does this mean? Consider this HTML document:
5050
<html lang="en">
5151
<head>
5252
<title>Styled Heading</title>
53-
<link href="style/main.css" media="screen">
53+
<link href="style/main.css" media="screen" />
5454
</head>
5555
<body>
5656
<h1>I am Red!!</h1>
@@ -71,7 +71,7 @@ Loading the document in your browser shows the heading, but the color will be bl
7171
To create the link and load the stylesheet, specify a valid value such as `stylesheet`:
7272

7373
```html
74-
<link rel="stylesheet" href="style/main.css" media="screen">
74+
<link rel="stylesheet" href="style/main.css" media="screen" />
7575
```
7676

7777
Reloading the document now shows the heading as red.
@@ -106,7 +106,7 @@ Here's what each stylesheet might contain:
106106
/* main.css - Default modern layout */
107107
.article {
108108
display: grid;
109-
font-family: 'Helvetica Neue', sans-serif;
109+
font-family: "Helvetica Neue", sans-serif;
110110
font-size: 1rem;
111111
gap: 2rem;
112112
grid-template-columns: 1fr 18.75rem;
@@ -257,7 +257,7 @@ The easiest way to support the vast array of screen resolutions is to use a scal
257257
The first icon we'll add to our head is an SVG icon:
258258

259259
```html
260-
<link rel="icon" href="favicon.svg" sizes="all" type="image/svg+xml">
260+
<link rel="icon" href="favicon.svg" sizes="all" type="image/svg+xml" />
261261
```
262262

263263
You'll notice a new attribute in the above snippet: the `sizes` attribute. This allows us to define and specify different sized icons for different resolutions when using formats like Portable Network Graphics (PNG). Because an SVG can scale up or down infinitely, we use the special keyword `all`.
Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
---
2+
title: "Introduction to the HTML Comprehensive Guide"
3+
keywords: html, html standard, web development, html guide, html tutorial, web standards, whatwg, html living standard, html specification, web markup, html elements, html attributes, dom, web accessibility, html conformance
4+
description: A comprehensive guide to HTML for developers. Learn the HTML Living Standard, elements, attributes, and best practices. From parsing to accessibility, master modern HTML development.
5+
---
6+
7+
HTML is the backbone of the web. Every web page, whether a simple document or a complex application, is built on it. When you open a browser, you are looking at HTML in action: it defines structure, meaning, and the hooks that connect to CSS, JavaScript, and APIs.
8+
9+
At first glance, HTML seems straightforward (just tags and attributes), but under the surface lies a detailed set of rules that browsers follow. These rules are codified in the **HTML Living Standard**, maintained by the Web Hypertext Application Technology Working Group (WHATWG).
10+
11+
## A living language
12+
13+
Unlike earlier specifications that were released in fixed versions (HTML4, XHTML, HTML5), the Living Standard is continuously updated. There is no "HTML6" waiting in the wings. Instead, the standard evolves gradually, reflecting the pace of change on the web itself. Features are added, revised, or marked obsolete as browsers converge on common behavior.
14+
15+
This approach acknowledges a truth: the web cannot stand still. A living one ensures that what is documented is what is implemented in practice.
16+
17+
The HTML specification is not only one text. The canonical version at [html.spec.whatwg.org](https://html.spec.whatwg.org/) is written primarily for implementers: browser vendors and standards contributors. It contains every rule needed to parse markup, build DOM trees, and handle edge cases, right down to how invalid code should be corrected. For developers, there is also a **developer-friendly view** at [html.spec.whatwg.org/dev](https://html.spec.whatwg.org/dev/), which trims some of the implementer-focused detail. Even so, it remains a specification, not a tutorial.
18+
19+
## Why this book exists
20+
21+
This book follows a simple philosophy: _"I read the spec so you don't have to."_
22+
23+
The HTML spec, in both implementer and developer editions, is rigorous and precise. That rigor makes it invaluable for browser engineers but challenging for practitioners who simply want to write correct, future-proof HTML. Developers looking for answers often end up wading through parsing algorithms or historical notes. These details do not directly help them.
24+
25+
This book reshapes the raw material of the specification into a guide for developers. It distills, organizes, and explains. The goal is not to replace the standard, but to make it accessible. Where the spec gives you the rule, this book explains the purpose. Where the spec outlines a parsing algorithm, this book shows the impact on your markup.
26+
27+
## A short history
28+
29+
HTML was born in 1991 when Tim Berners-Lee created a small set of tags to describe documents on the first web servers. In 1995, HTML 2.0 was published as the first formalized standard. Over the years, more versions followed, sometimes introducing improvements, sometimes breaking compatibility.
30+
31+
In the early 2000s, XHTML attempted to reshape HTML into strict XML. Adoption stalled. Developers and browsers alike found it unforgiving. At the same time, demand for richer web applications grew. The WHATWG formed in 2004 with the goal of extending HTML pragmatically, leading to HTML5, a standard that reconnected with real-world needs. From there, the Living Standard was born, with no more numbered versions.
32+
33+
That history matters because it explains HTML's unusual character: a mix of elegant principles and messy compromises. The language has to accommodate everything from modern single-page apps to decades-old documents still online. Understanding HTML deeply means understanding not just _how_ it works, but _why_ it works the way it does.
34+
35+
## Scope of this book
36+
37+
This book does not attempt to be a beginner's crash course. It is for developers who want to understand HTML thoroughly: every element, every attribute, every model of content.
38+
39+
Covered in detail:
40+
41+
- All standard elements and attributes in the Living Standard.
42+
- Concepts such as parsing, the DOM, and content models.
43+
- Key APIs where HTML defines hooks (forms, media, canvas, custom elements).
44+
- Accessibility requirements that shape markup.
45+
- Conformance rules that distinguish correct from incorrect usage.
46+
47+
Covered lightly or excluded:
48+
49+
- CSS and JavaScript in their full scope (addressed only when they intersect with HTML).
50+
- Browser engine internals beyond what is necessary to explain element behavior.
51+
- Non-standard features, deprecated quirks, and historical dead ends (mentioned only where context is useful).
52+
53+
Each chapter aims to balance theory with practice. You will see both what the spec mandates and how to apply that knowledge when building web pages and applications.
54+
55+
## Tools to work with HTML
56+
57+
The HTML spec is the authoritative source, but no developer works with the spec alone. Several tools and references are indispensable:
58+
59+
- **Validators and conformance checkers**: [The W3C Nu HTML Checker](https://validator.w3.org/nu/) is the main tool to verify markup. It enforces conformance rules and flags errors or warnings.
60+
- **Accessibility testing tools**: Automated checkers and manual audit frameworks (such as [axe](https://www.deque.com/axe/) or [WAVE](https://wave.webaim.org)) reveal issues that affect users with disabilities. Accessibility is not optional; it is central to modern HTML.
61+
- [**MDN Web Docs**](https://developer.mozilla.org): While the specification defines the rules, MDN offers approachable explanations, examples, and browser-compatibility data. It is the practical reference most developers use day to day.
62+
63+
These tools complement the material in this book. Where the book provides deep understanding, the tools provide immediate feedback and applied knowledge.
64+
65+
## Reading this book
66+
67+
The organization of this book mirrors the structure of the specification, but rephrased and contextualized for developers. You do not need to read the spec in parallel, though references are provided for those who want to verify or explore further.
68+
69+
The aim is to give you a clear mental model of the language. You will learn not just how to write correct markup, but how browsers interpret it, why certain rules exist, and how to make informed choices as a developer.
70+
71+
By the end, you will not only be able to write HTML that works, but also HTML that is robust, accessible, and future-proof.

src/content/docs/index.mdx

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ hero:
88
file: ../../assets/htmlcg-icon.svg
99
actions:
1010
- text: Start reading and learning
11-
link: book/chapter001/
11+
link: book/introduction/
1212
icon: right-arrow
1313
variant: primary
1414
---
@@ -24,9 +24,10 @@ import { Card, CardGrid } from "@astrojs/starlight/components";
2424
to this guide.
2525
</Card>
2626
<Card title="Start learning" icon="open-book">
27-
[Start learning today!](book/chapter001/)
27+
[Start learning today!](book/introduction/)
2828
</Card>
2929
<Card title="Support the book" icon="star">
30-
[Support the project on Patreon](https://patreon.com/SchalkNeethling)
30+
[Support the project on
31+
Patreon](https://www.patreon.com/cw/schalk_neethling)
3132
</Card>
3233
</CardGrid>

0 commit comments

Comments
 (0)