文档是任何技术项目的重要组成部分。好的文档会告诉最终用户如何运行程序、如何使用程序或如何编译程序。对于许多项目来说，纯文本文档是标准。毕竟，每个系统都可以显示纯文本文件。
然而，纯文本是有限制的。纯文本文件缺少格式化元素，如斜体文本、粗体文本和标题。为了添加这些元素，我们可以利用 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 条评论