前言
在现今的前端开发中，很多开发者们都在使用渐进式 JavaScript 反应式应用程序的工具，其中包括我们要介绍的一个 NPM 包 - idyll-document。 通过 idyll-document，你可以快速简便的创建可视化交互式文档和报告。
什么是 idyll-document?
Idyll 是一个用于创建交互式且高度可视化的文档和报告的开源 Javascript 库。它遵循着一个简化版的 Markdown 语法，并提供了丰富的组件、交互式视差效果和动画效果，使文档更具可读性和可交互性。
其中，idyll-document 是 Idyll 提供的一个 NPM 包，这个包主要是代替 Idyll 的交互式运行环境，它允许将 Idyll 的 Markdown 语法转化成一个可独立部署的静态 HTML 文件，从而方便我们在本地文件系统或在 Web 服务器上展示和分享 idyll 文档。下面我将为大家详细介绍如何使用 idyll-document。
安装
在开始使用 idyll-document 之前，我们需要先安装它。在命令行终端输入以下代码进行安装：
npm install -g idyll-document
以上代码的含义是，通过 npm 工具来全局安装 idyll-document 包。
使用方法
1. 创建一个新的 idyll 文档
在创建新的 idyll 文档之前，我们需要先设置文档所属的目录：
mkdir idyll-doc cd idyll-doc
以上代码意味着，我们先新建一个名叫 idyll-doc 的文件夹，将文档放到这个文件夹中，然后通过 cd 命令进入到这个文件夹。
接着，你可以使用以下命令来创建一个新的 idyll 文档:
idyll create doc
此时，你会看到 idyll-document 模板已经被创建并下载了所有需要的依赖。
2. 预览
成功创建了一个新的文档之后，我们需要预览这个文档并确保它能够正常运行。在命令行终端里输入以下代码，将启动一个本地服务器：
npm start
该命令会在 3000 端口启动一个本地的开发服务器。
然后你可以在浏览器中输入 http://localhost:3000 来访问 idyll 文档。
3. 构建
在预览完文档之后，我们需要使用以下命令将它打包并构建为静态 HTML 文件：
npm run build
这个命令执行完成后，你可以在 idyll-doc 目录里找到一个名为”build”文件夹，里边包含了静态 HTML 文件和所有的依赖资源,该文件夹的根目录下有一个名为”index.html”的文件。
4. 部署
通过上一篇介绍，我们已经成功完成了 idyll 文档的构建，现在我们需要将它部署到我们想要分享和展示的地方。这里我将以 Github Pages 为例，介绍如何将 idyll 文档部署到 Github Pages 上。
首先，我们需要在 Github 上新建一个 repository。
然后，将构建好的静态 HTML 文件复制到 repository 的根目录下。
最后，在 repository 的 settings 中找到 Github Pages ，选择 master branch，并在启动自动部署。
现在你可以在你的 Github Pages 上访问 idyll 文档。
示例代码
下面是一个简单的 idyll 文档，它展示了如何创建一个简单的交互式文档，通过此代码来帮助大家更好地理解 idyll-document 的基本用法：
-- -------------------- ---- ------- - ------------ ------- -- -- ----- --------- -- ---- --------- - -- ----- -- ----------- --- -- ------ --- ------- ----------- ------- ----- ------ ------ ----- ----- --------------------------------------------------- -------- ------ ----- ------------ ----- ---------- ----- -------- ----- -------------- ----- -- ---- - ----- ----- -- ------ ---- ----- ------
这段代码展示了 Idyll 的基本语法，可以作为新手教程动手操作。最终效果展示如下：
结语
通过本文，我们已经详细介绍了如何使用 idyll-document。Idyll 提供了高度可视化的文档和报告，可以使我们更好地展示我们的工作成果。希望本文可以帮助初学者更好的理解如何使用 idyll-document。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5eedbe2db5cbfe1ea0611b31