HTML5 标记语言速成指南：以 learnxinyminutes-docs 葡萄牙语版 html.md 为核心的标签语法与实战解析

• 文档
• 教程

HTML（HyperText Markup Language，超文本标记语言）是构建万维网页面的基础语言。本文以 learnxinyminutes-docs 仓库中的 葡萄牙语版 HTML 教程 为骨架，系统讲解 HTML5 的核心语法、文档结构、常用标签与文件规范，并结合仓库的源码级证据（frontmatter 元数据、lint 校验脚本、贡献规范）展开纵深解读。读完本文，你将能够从零写出一个结构完整、语义正确的 HTML5 页面，理解注释、标题、段落、超链接、列表、图片与表格等全部基础标签的用法，并了解该教程在 Learn X in Y minutes 项目中的组织方式与质量标准。

HTML 是什么：超文本标记语言的核心概念

根据 pt-br/html.md 的定义，HTML 是 "HyperText Markup Language" 的缩写，是一门允许我们为万维网编写页面的语言。它有四个关键特性：

• 标记语言（Linguagem de marcação）：它不是编程语言，而是通过代码指示文本和数据应当如何显示的组织方式；
• 纯文本文件：HTML 文件本质上是简单的文本文件，任何文本编辑器都可以创建和编辑；
• 标签（Tags）驱动的结构：标记（marcação）是一种组织页面数据的方法——将数据用**开始标签（opening tags）和结束标签（closing tags）**包围起来，为所包裹的文本赋予意义；
• 多版本演进：与其他计算机语言一样，HTML 存在多个版本，本教程聚焦HTML5。

与之对应，仓库根目录的英文原版 html.md 给出了完全一致的定义，二者互为参照。值得强调的是，html.md 中有一句醒目的警示："HTML is NOT a programming language"（HTML 不是编程语言）——这一点在阅读任何 HTML 教程时都应当牢记，HTML 负责描述内容的语义与结构，而不具备变量、逻辑分支等编程能力。

动手实践：推荐在线实验环境

pt-br/html.md 建议读者在逐步学习教程的过程中，通过 CodePen 这类在线平台实时测试不同的标签与元素：

• 输入标签后立即看到渲染效果；
• 观察每个元素的行为与默认样式；
• 通过反复修改加深对语言的理解。

该教程明确说明，其主要焦点是 HTML 的语法和一些实用技巧，而非面面俱到的特性罗列。后续所有代码示例均可在任何本地.html文件或在线沙盒中直接运行验证。

HTML5 文档骨架：第一个完整示例逐行剖析

原文首先给出了一个完整的 HTML5 文件示例，这是理解整个文档结构的最佳入口。以下示例保留了原文的完整结构，注释已译为中文（仓库原文件中为葡萄牙语注释，见 pt-br/html.md）：

<!-- 注释就按本行的方式被包围起来！ --> <!-- #################### 标签（Tags） #################### --> <!-- 下面是一个我们将要分析的 HTML 文件示例。 --> <!doctype html> <html> <head> <title>Meu Site</title> </head> <body> <h1>Olá, mundo!</h1> <a href="https://exemplo.com">点此查看实际渲染效果</a> <p>这是一个段落。</p> <p>这是另一个段落。</p> <ul> <li>这是一个无序列表（项目符号列表）中的一项</li> <li>这是另一项</li> <li>这是列表中的最后一项</li> </ul> </body> </html>

这个文件虽然只有十余行，却已经覆盖了 HTML5 文档的全部四大组成部分：文档类型声明、根元素、头部元数据区和正文内容区。下面逐段拆解。

文档类型声明<!doctype html>

每个 HTML 文件必须以<!doctype html>开头（见 pt-br/html.md），它的作用是向浏览器声明"这是一个 HTML 页面"，从而让浏览器以标准模式（standards mode）解析文档。之后：

• 紧接着打开<html>根标签；
• 文件结尾必须用</html>闭合；
• </html>之后不应再出现任何内容。

根元素<html>

<html>是文档的根元素，所有其他标签都位于<html>与</html>之间。在开闭标签之间，原文指出了文档的两个主要分区：

• <head>头部：存放描述信息与附加信息，这些内容不会显示在浏览器窗口中，统称为元数据（metadados）；
• <body>正文：承载所有要显示给用户的内容。

头部<head>与标题<title>

<head> <title>Meu Site</title><!-- <title> 标签告诉浏览器在标题栏和标签页名称中显示什么标题。 --> </head>

<title>标签位于<head>之内，用于指定浏览器标题栏与标签页名称中显示的文本。原文强调：到<head>为止，任何内容都不会出现在浏览器窗口的可视区域中，必须靠<body>来填充可见内容。

正文<body>与可见内容

<body> <h1>Olá, mundo!</h1> <a href="https://exemplo.com">点此查看实际渲染效果</a> <p>这是一个段落。</p> <p>这是另一个段落。</p> <ul> <li>这是一个无序列表（项目符号列表）中的一项</li> <li>这是另一项</li> <li>这是列表中的最后一项</li> </ul> </body>

原文通过这个例子说明了"创建 HTML 文件可以非常简单"——仅凭一个<h1>、一个<a>、两个<p>和一个<ul>，就已经构成一个语义完整的页面。

注释：给 HTML 添加说明

原文指出注释的写法：<!--与-->之间的一切内容都会被浏览器忽略（见 pt-br/html.md）。注释既可以写单行，也可以跨越多行——英文原版 html.md 特别展示了多行注释的写法。注释是教学文档与团队协作的重要工具：解释某段代码的意图、标记待办事项、临时屏蔽调试代码等，都不会影响页面渲染。

内容标签详解：标题、段落、超链接与列表

标题体系<h1>~<h6>

<h1>标签创建一级标题，是页面中最重要、级别最高的标题。原文补充说明：还存在从最重要（<h2>）到更精细（<h6>）的各级子标题（见 pt-br/html.md）。合理使用标题层级不仅是排版需求，更是页面语义结构与可访问性的基础。

段落<p>

<p>标签用于在页面中插入一段文本（pt-br/html.md）。多个<p>依次排列即可组织多段正文。

超链接<a>与href属性

<a href="https://exemplo.com">链接文字</a>

<a>创建指向href=""属性所填地址的超链接（pt-br/html.md）。href是锚元素最核心的属性，其值可以是一个完整的 URL，也可以是站内相对路径、锚点或mailto:等特殊协议。

列表<ul>、<ol>与<li>

• <ul>创建无序列表（项目符号列表，即 bullet list）；
• 若要创建有序列表，应改用<ol>，浏览器会为第一项显示1.、第二项显示2.，依此类推（pt-br/html.md）；
• 每一项内容用<li>（list item）包裹。

<ul> <li>这是一个无序列表中的一项</li> <li>这是另一项</li> <li>这是列表中的最后一项</li> </ul>

媒体与表格：<img>与<table>

插入图片<img>与src属性

<img src="https://exemplo.com/imagem.gif"/>

<img />标签用于插入图片（pt-br/html.md）。图片来源通过src=""属性指定：

• src的值可以是网络 URL；
• 也可以是你计算机上的本地文件路径。

注意<img />属于自闭合（void）元素，斜杠/>表示该标签不需要单独的结束标签。原文示例中使用的是 GIF 动图，实际开发中同样适用于.png、.jpg、.webp、.svg等格式。

创建表格<table>、<tr>、<th>、<td>

原文给出了一个完整的表格示例（pt-br/html.md），涉及四个层层嵌套的标签：

• <table>：开启一张表格；
• <tr>（table row）：创建一行；
• <th>（table header）：创建列标题；
• <td>（table data）：创建单元格。

<table> <tr> <th>第一个表头</th> <th>第二个表头</th> </tr> <tr> <td>第一行，第一列</td> <td>第一行，第二列</td> </tr> <tr> <td>第二行，第一列</td> <td>第二行，第二列</td> </tr> </table>

这个示例清晰地展示了表格的层级关系：<table>内是若干<tr>行，行内由<th>或<td>组成单元格，从而形成"表头行 + 数据行"的标准二维结构。

文件使用规范与重要提醒

原文在 Uso（使用） 一节给出了两个关键事实：

• HTML 文件使用.html或.htm扩展名保存；
• 其MIME 类型是text/html——浏览器正是依据该 MIME 类型识别并渲染 HTML 文档（例如 Web 服务器配置或 HTTP 响应头中的Content-Type: text/html）。

同时再次强调：HTML 不是编程语言，它是一门标记语言，负责描述内容的结构与语义。

仓库视角：这篇教程在 learnxinyminutes-docs 中的组织方式与规范

Learn X in Y minutes 项目的定位，正如 README.md 所描述："以有效、带注释的代码形式呈现的旋风式语言导览"。这一理念在 HTML 教程中体现得淋漓尽致——整篇教程本身就是一段可运行的、注释密集的 HTML 代码。以下规范细节均可以从仓库中直接验证：

Frontmatter 元数据

每个文档文件以 YAML frontmatter 开头。英文原版 html.md 声明了name: HTML与filename: learnhtml.txt（该文件用于站点生成可下载的代码文件）；葡萄牙语版 pt-br/html.md 则通过contributors与translators分别记录原作者 Christophe THOMAS 和译者 Robert Steed。

Lint 校验脚本

仓库的 lint/frontmatter.py 规定了 frontmatter 允许的键集合：name、category、filename、contributors、translators等，并校验其类型——例如contributors/translators必须是"字符串列表的列表"，每个条目至多含两项（作者名 + 可选 URL），见 校验逻辑。这保证了包括本文档在内所有翻译文件元数据的一致性与机器可读性。

风格指南

CONTRIBUTING.md 对文档写作提出了明确要求，正是这些规范塑造了本教程的形态：

• 代码行尽量控制在 80 字符以内，保证代码块不溢出；
• 示例优先于叙述（"Prefer example to exposition"）——能用代码说明的绝不多写文字，这正是本文通篇"代码即教程"风格的原因；
• 惜字如金（"Eschew surplusage"）——面向有一定经验的程序员，只解释与主题直接相关的概念；
• 使用 UTF-8 编码。

翻译文档还需额外补充translators字段（CONTRIBUTING.md），非英语文档可继承英语原文的 frontmatter 值并加以覆盖——这正是 pt-br/html.md 中同时出现原作者与译者的原因。

多语言一致性

HTML 教程在仓库中拥有完整的翻译矩阵：英文原版 html.md、葡萄牙语版 pt-br/html.md、简体中文版 zh-cn/html.md，以及德、西、法、俄、日等多语版本，内容结构保持一致，仅注释语言不同。这为多语言读者提供了完全对等的学习路径。

进一步学习方向

原文在结尾列出了三个学习资源方向（详见 pt-br/html.md，此处不附外部链接）：

1. Wikipedia 的 HTML 词条：了解 HTML 的历史、版本演进与标准背景；
2. MDN 的 HTML 教程：Mozilla 开发者网络的权威参考，包含每个元素的完整文档；
3. W3Schools 的 HTML 入门：面向初学者的分步交互式教程。

此外，结合 README.md 的项目理念，强烈建议你亲自修改本文中的示例代码：改变标题级别、增删列表项、给表格加行——每一次改动后刷新浏览器，都能直观感受到标签与渲染结果之间的对应关系。从"看懂"到"写出来"，正是掌握 HTML 的唯一捷径。

• 文档
• 教程