文档是任何技术项目的重要组成部分。好的文档会告诉最终用户如何运行程序、如何使用程序或如何编译程序。对于许多项目来说，纯文本文档是标准。毕竟，每个系统都可以显示纯文本文件。
然而，纯文本是有限的。纯文本文件缺少格式化元素，如斜体文本、粗体文本和标题。为了添加这些元素，我们可以利用 HTML。超文本标记语言 (HTML) 是所有 Web 浏览器中使用的标记语言。只需稍加努力，您就可以使用 HTML 编写可供所有人阅读的项目文档。
HTML 使用一系列用尖括号括起来的标签来控制文档的不同部分的显示方式。这些标签定义了 HTML 文档中的元素，例如文档标题、段落、斜体文本、粗体文本和其他类型的文本。几乎每个标签都是成对出现的：一个开始标签，例如 <p> 用于开始一个段落，以及一个结束标签用于结束元素，例如 </p> 用于结束一个段落。使用这些标签时，请记住这条规则：如果您打开一个标签，您需要关闭它。未正确关闭标签可能会导致 Web 浏览器错误。
有些标签定义了 HTML 文档中的块级元素，而另一些则是行内元素。有关块级元素和行内元素的更多信息，请阅读我的另一篇文章，关于 HTML 简易入门。
启动一个空文档
首先创建一个样板空 HTML 文档。每个 HTML 文档都应提供文档类型声明。在 HTML 文件的第一行使用单标签 <!DOCTYPE html> 来定义 HTML 文档。HTML 标准还要求页面将文档文本包装在两个块级元素中：<html> 用于定义 HTML 文档，<body> 用于定义正文文本。虽然 HTML 不要求缩进每个新的代码块，但我仍然添加它，以便您可以看到 <body> 实际上是“在”<html> 块“内部”
<!DOCTYPE html>
<html>
<body>
</body>
</html>HTML 文档在 <body> 之前还需要一个 <head> 块，用于提供关于页面的额外信息，称为元数据。唯一必需的元数据是文档的标题，由 <title> 元素定义。一个空文档可能如下所示
<!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
</head>
<body>
</body>
</html>添加文本
让我们通过将现有的纯文本“Readme”文件改编为 HTML 来练习一些 HTML 知识。在本例中，我将使用关于如何玩一款名为 Simple Senet 的开源棋盘游戏的部分文档
HOW TO PLAY SIMPLE SENET
The game will automatically "throw" the throwing sticks for you, and
display the results in the lower-right corner of the screen.
If the "throw" is zero, then you lose your turn.
When it's your turn, the game will automatically select your first
piece on the board. You may or may not be able to make a move with
this piece, so select your piece to move, and hit Space (or Enter) to
move it. You can select using several different methods:
- Up/down/left/right to navigate to a specific square.
- Plus (+) or minus (-) to navigate "left" and "right" on the
board. Note that this will automatically follow the "backwards S"
shape of the board.
- Tab to select your next piece on the board.
To quit the game at any time, press Q (uppercase Q) or hit Esc, and
the game will prompt if you want to forfeit the game.
You win if you move all of your pieces off the board before your
opponent. It takes a combination of luck and strategy!首先将此 Readme 文本添加到您的空 HTML 文件中。HTML 页面的主要内容是 <body>，因此您将文本放在此处
<!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
</head>
<body>
HOW TO PLAY SIMPLE SENET
The game will automatically "throw" the throwing sticks for you, and
display the results in the lower-right corner of the screen.
If the "throw" is zero, then you lose your turn.
When it's your turn, the game will automatically select your first
piece on the board. You may or may not be able to make a move with
this piece, so select your piece to move, and hit Space (or Enter) to
move it. You can select using several different methods:
- Up/down/left/right to navigate to a specific square.
- Plus (+) or minus (-) to navigate "left" and "right" on the
board. Note that this will automatically follow the "backwards S"
shape of the board.
- Tab to select your next piece on the board.
To quit the game at any time, press Q (uppercase Q) or hit Esc, and
the game will prompt if you want to forfeit the game.
You win if you move all of your pieces off the board before your
opponent. It takes a combination of luck and strategy!
</body>
</html>在没有进一步更改的情况下，当您在 Web 浏览器中查看此 HTML 文档时，它看起来完全错误。这是因为 HTML 像大多数标记系统一样，从输入文件中收集单词并在输出中填充段落。因为您尚未添加其他标记，所以 Web 浏览器将文本显示在单个段落中
(Jim Hall, CC BY-SA 4.0)
正文段落
将此 Readme 文件更新为 HTML 的第一步是标记每个段落，以便 Web 浏览器可以正确显示它。定义段落的标签是 <p>。虽然此文件中的并非所有内容实际上都是段落，但首先将所有内容都包装在 <p> 和 </p> 标签中
<!DOCTYPE html>
<html>
<head>
<title>Title of the document</title>
</head>
<body>
<p>HOW TO PLAY SIMPLE SENET</p>
<p>The game will automatically "throw" the throwing sticks for you, and
display the results in the lower-right corner of the screen.</p>
<p>If the "throw" is zero, then you lose your turn.</p>
<p>When it's your turn, the game will automatically select your first
piece on the board. You may or may not be able to make a move with
this piece, so select your piece to move, and hit Space (or Enter) to
move it. You can select using several different methods:</p>
<p>- Up/down/left/right to navigate to a specific square.</p>
<p>- Plus (+) or minus (-) to navigate "left" and "right" on the
board. Note that this will automatically follow the "backwards S"
shape of the board.</p>
<p>- Tab to select your next piece on the board.</p>
<p>To quit the game at any time, press Q (uppercase Q) or hit Esc, and
the game will prompt if you want to forfeit the game.</p>
<p>You win if you move all of your pieces off the board before your
opponent. It takes a combination of luck and strategy!</p>
</body>
</html>这使 Readme 看起来更像您想要阅读的文档。当您在 Web 浏览器中查看新文档时，每个段落都从新行开始，并且在上方和下方有一些额外的空间。段落是块级元素最常见的示例。
(Jim Hall, CC BY-SA 4.0)
标题和子标题
您内容中的第一行是文档的标题，因此您应该将其设为标题。HTML 提供了六个级别的标题，从 <h1> 到 <h6>。在大多数文档中，您可以使用 <h1> 定义文档的标题，使用 <h2> 定义主要子节。在您的示例 Readme 文档中进行此更改。使用程序名称（“Simple Senet”）作为主节标题，并使用“How to Play”作为文档中的子节。
请注意，在本示例中，我还更新了文档元数据中的 <title> 以使用与 <h1> 标题相同的标题。这实际上不会更改浏览器显示文档的方式，但这是一个很好的做法
<!DOCTYPE html>
<html>
<head>
<title>Simple Senet</title>
</head>
<body>
<h1>Simple Senet</h1>
<h2>How to Play</h2>
...
</body>
</html>通过添加这些节标题，您使文档更易于阅读
(Jim Hall, CC BY-SA 4.0)
有序列表和无序列表
您的文档包含一个列表，其中列出了导航棋盘游戏的不同方式。由于此文档最初是纯文本文件，因此列表中的每个项目都以连字符开头。但是您可以使用 HTML 将这三个段落定义为列表项。
HTML 支持两种类型的列表：有序列表和无序列表。有序列表 <ol> 是一个编号序列，您可以用来定义一系列步骤。无序列表 <ul> 定义一个项目列表，这些项目可能相关也可能不相关，但通常不按顺序完成。这两个列表都使用列表项 <li> 作为列表中的条目。
更新 Readme 文档以使用有序列表而不是段落。这以编号列表的形式呈现了三个导航选项
<ol>
<li>Up/down/left/right to navigate to a specific square.</li>
<li>Plus (+) or minus (-) to navigate "left" and "right" on the
board. Note that this will automatically follow the "backwards S"
shape of the board.</li>
<li>Tab to select your next piece on the board.</li>
</ol>这以编号列表的形式呈现了三个选项
(Jim Hall, CC BY-SA 4.0)
但是，这三个项目实际上不是步骤序列，而是移动 Simple Senet 游戏中选择的不同选项。因此，我们想要使用无序列表而不是有序列表。这需要将文档中的 <ol> 更新为 <ul>
<ul>
<li>Up/down/left/right to navigate to a specific square.</li>
<li>Plus (+) or minus (-) to navigate "left" and "right" on the
board. Note that this will automatically follow the "backwards S"
shape of the board.</li>
<li>Tab to select your next piece on the board.</li>
</ul>无序列表对每个列表项使用项目符号，因为这些条目不是序列的一部分
(Jim Hall, CC BY-SA 4.0)
粗体和斜体
您可以通过应用粗体和斜体样式来突出显示文档中的某些信息。这些是技术写作中非常常见的文本样式。您可以使用粗体来突出显示重要信息，或使用斜体来强调关键短语和新术语。
粗体标签最初定义为 <b>，但较新版本的 HTML 标准更喜欢使用 <strong> 标签来表示强烈的强调，例如一组指令中的关键步骤。这两个标签都有效，但在语义上略有不同。<b> 现在意味着“引起注意”。
同样，原始 HTML 标准使用 <i> 表示斜体文本。更高版本的 HTML 而是更喜欢使用 <em> 来强调文本的某些部分。相反，<i> 现在标识惯用文本或技术术语。
在本示例中，使用粗体标识单字母按键，使用斜体指示键盘上的特殊键，如Enter 和 Space。为简单起见，此处使用 <b> 和 <i> 标签（但您也可以使用 <strong> 和 <em> 标签来获得相同的效果：）
<!DOCTYPE html>
<html>
<head>
<title>Simple Senet</title>
</head>
<body>
<h1>Simple Senet</h1>
<h2>How to Play</h2>
<p>The game will automatically "throw" the throwing sticks for you, and
display the results in the lower-right corner of the screen.</p>
<p>If the "throw" is zero, then you lose your turn.</p>
<p>When it's your turn, the game will automatically select your first
piece on the board. You may or may not be able to make a move with
this piece, so select your piece to move, and hit <i>Space</i> (or <i>Enter</i>) to
move it. You can select using several different methods:</p>
<ul>
<li><i>Up</i>/<i>down</i>/<i>left</i>/<i>right</i> to navigate to a specific square.</li>
<li>Plus (<b>+</b>) or minus (<b>-</b>) to navigate "left" and "right" on the
board. Note that this will automatically follow the "backwards S"
shape of the board.</li>
<li><em>Tab</em> to select your next piece on the board.</li>
</ul>
<p>To quit the game at any time, press <b>Q</b> (uppercase Q) or hit <i>Esc</i>, and
the game will prompt if you want to forfeit the game.</p>
<p>You win if you move all of your pieces off the board before your
opponent. It takes a combination of luck and strategy!</p>
</body>
</html>这些额外的样式有助于特殊项目在文本中脱颖而出
(Jim Hall, CC BY-SA 4.0)
编写文档的目的是为了让用户了解如何使用软件，因此每个开源项目都应努力以易于阅读的方式编写文档。使用一些基本的 HTML 标签，您可以编写文档，更清晰地向用户呈现信息。
有关使用 HTML 编写文档的更多信息，请查看 MDN（Mozilla 开发者网络，由 Mozilla Web 项目托管）上的完整 超文本标记语言参考。
6 条评论