在前端开发过程中，写好文档对于代码的可维护性和团队协作都非常重要。然而，写好的文档还需要被呈现出来。@preamp/documentation 就是一个将 Markdown 格式的文档转换为漂亮网页的 npm 包。在这篇文章中，我们将会学习如何使用它来生成我们的文档，并制作出一个漂亮的示例效果。
前置条件
在开始之前，我们需要先确保我们拥有以下这些环境和工具：
使用步骤
安装 npm 包
使用 npm 命令安装 @preamp/documentation。
npm install @preamp/documentation
创建文档
你可以写你的文档在任何地方，只要它是 Markdown 格式。在这篇文章中，我们将使用一个示例文档作为例子。这个文档用到了代码块，链接，列表，并且给出了一个例子。
-- -------------------- ---- ------- - -- ----------------- ---------------------- -- --- --------- ----- ------------------- ---------展开代码
链接
这里是一个链接到 Google 的示例。
列表
- 项1
- 项2
- 项2.1
- 项2.2
例子
这里有一个例子：
-- -------------------- ---- ------- --------- ----- ----- ---------- ------ ----- ---------------- ---------------------- ----- ---------------- ----------------- ------- ------ ---- ------------- --------- ---------- ------ ------- ------------------------- ------- -------展开代码
-- -------------------- ---- ------- --- ------ ---------------------- --------------------- ---------------------------------------- ------- - ------------- ----------------- --------------- --------- -------- --------- -展开代码
我们将该文件保存为 preamp.json。
运行命令
最后，我们需要运行 @preamp/documentation 的命令。我们可以将它添加到我们的 package.json 文件的 scripts 选项中，以便我们可以方便地运行它。在这里，我们为它添加了一个 docs 命令。
-- -------------------- ---- ------- - ------- ---------- ---------- -------- ---------- - ------- -------- -- ------------------ - ------------------------ -------- - -展开代码
现在，我们可以在控制台中运行以下命令：
npm run docs@preamp/documentation 应该会生成一个文件夹，该文件夹包含一个漂亮且易于导航的 HTML 网页版本的我们的文档。
插入代码块
如果你需要在你的文档中插入代码块，它的格式如下：
```语言名称
你的代码-- -------------------- ---- ------- ---------------------- ---------- ---- ----------- -- --- --------- ----- ------------------- ---------展开代码
-- -------------------- ---- ------- --- --------------------- --------------- -- ---- -------------------- ----------- ---------展开代码
例如，在示例文档中，我们可以插入一个示意图。
## 插入图像 
在 @preamp/documentation 命令运行后，我们的图片将被展示在我们的文档中。
自定义主题
@preamp/documentation 允许我们自定义主题。在 preamp.json 文件中，我们可以指定主题名称。如果你想自定义你的主题，你可以从提供的主题中创建自己的主题。主题的结构可以参照其它主题进行修改。在以下的例子中，我们将使用一个自定义主题。
创建主题目录
首先，让我们创建一个目录，它将包含我们的主题。
mkdir my-theme
创建样式文件
接着，我们要在 my-theme 目录中创建一个 index.css 文件，并继承我们的主题。
-- -------------------- ---- ------- --- - -- --------------------- ----- -- ------- ------------------------------------------------- --- - --------- -- ---- - ------------ ----------- - --- - ----------------- -------- -------- ----- -------------- ---- ------- --- ----- ----- - --- -- - -------------- ----- - -- - ---------- ----- ------------ ----- -展开代码
创建配置文件
在 my-theme 目录中，我们还需要创建一个名为 preamp.json 的配置文件，用于指定我们的自定义主题。
{ "superTheme": "default", "styles": ["./index.css"] }
编辑 preamp.json 文件
最后，我们还需要编辑 preamp.json 文件，在 theme 属性中指定我们的自定义主题的名称。
{ "inputFiles": ["./example.md"], "outputFolder": "./docs", "theme": "my-theme" }
现在，我们就可以重新运行 @preamp/documentation 命令，看看我们的自定义主题是如何应用到我们的文档中的。
结论
@preamp/documentation 提供了一个简单且易于使用的方式，将 Markdown 格式的文档转化为漂亮的网页版本。它还提供了个性化样式和其他功能，以便我们根据我们的需求进行自定义，并满足我们的特定需求。我希望这篇文章能够帮助你学会如何使用 @preamp/documentation 来改善你的文档，并使它更易于使用和漂亮。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/131839
