安装指南

在本页，您将学习：

如何安装 Asciidoctor.js。
如何在您的 JavaScript 环境中设置 Asciidoctor.js。

安装 Asciidoctor.js

我们推荐使用最新的长期支持（LTS）版本的 Node。虽然您可以使用其他版本的 Node，但 Asciidoctor.js 仅在活动的 LTS 版本上进行过测试。

在您的机器上安装了活动的 Node LTS 版本后，打开终端并输入：

$ npm i asciidoctor

如果您更喜欢使用 Yarn 而不是 npm，您可以通过以下命令安装 Asciidoctor.js：

yarn add asciidoctor

Asciidoctor.js 提供了不同的构建版本，适用于不同的 JavaScript 环境。请参见下面的链接，选择适合您的版本，并查看使用说明。

基本浏览器设置

在 <script type="module"> 标签中引入 Asciidoctor.js。您可以使用 Asciidoctor() 实例化处理器。

<script type="module">
  import Asciidoctor from './node_modules/@asciidoctor/core/dist/browser/asciidoctor.js'
  const asciidoctor = Asciidoctor()
</script>

需要注意本地测试的问题——如果您尝试通过 file:// URL 本地加载 HTML 文件，您可能会遇到由于 JavaScript 模块安全要求导致的 CORS 错误。您需要通过服务器进行测试。

了解更多关于 JavaScript 模块的内容。

Node

const Asciidoctor = require('asciidoctor')

const asciidoctor = Asciidoctor()

AMD (System.js, RequireJS, etc)

requirejs(['asciidoctor'], function (asciidoctor) {
  //...
})

TypeScript

import Processor from 'asciidoctor'

const processor = Processor()

我们使用 processor 这个名称，以避免与 Asciidoctor 命名空间混淆。

Webpack

import Asciidoctor from 'asciidoctor'

const asciidoctor = Asciidoctor()

GraalVM

Node.js 应用

GraalVM 可以运行 Node.js 应用程序。

要安装 asciidoctor.js 模块，请使用 GraalVM 包中 /bin 文件夹中的 npm 可执行文件。

将以下代码片段保存为 app.js 文件，并保存在与 Node.js 模块安装目录相同的目录中：

app.js

const Asciidoctor = require('asciidoctor')

const asciidoctor = Asciidoctor()

然后，使用 GraalVM 中的 node 命令执行它（node 命令位于 GraalVM 包的 /bin 文件夹中）：

$ node app.js

嵌入到基于 JVM 的应用程序中

通过 Graal Polyglot API，您可以将 JavaScript 代码嵌入到基于 JVM 的应用程序中。不过，这目前是一个 实验性 功能。请随时分享您可能遇到的任何反馈或问题。

Graal Polyglot 功能提供的是一个 “纯” JavaScript（ECMAScript）引擎，而不是 Node.js 引擎。换句话说，Node.js 的功能，如 require 或核心模块（如 fs）将不可用。

要将 Asciidoctor.js 嵌入到 Java 应用程序中，创建以下代码片段并保存为 app.js 文件（已在 v21.1.0 上测试）：

app.js

var asciidoctor = Asciidoctor()

将文件 node_modules/asciidoctor.js/dist/graalvm/asciidoctor.js 复制到应用程序的资源文件夹中。然后创建一个名为 AsciidoctorGraalVM.java 的 Java 文件，内容如下：

AsciidoctorGraalVM.java

import org.graalvm.polyglot.Context;

import java.io.File;
import java.io.IOException;
import java.net.URISyntaxException;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.ArrayList;
import java.util.List;

public class AsciidoctorGraalVM {

  public static void main(String... args) {
    Context context = Context.newBuilder("js")
                                .allowIO(true)
                                .allowAllAccess(true)
                                .allowPolyglotAccess(PolyglotAccess.ALL)
                                .build();
    context.getPolyglotBindings().putMember("IncludeResolver", new IncludeResolver()); (1)
    context.eval("js", "var IncludeResolver = Polyglot.import('IncludeResolver');");
    ClassLoader classLoader = AsciidoctorGraalVM.class.getClassLoader();
    context.eval("js", "load('" + classLoader.getResource("asciidoctor.js") + "')"); (2)
    context.eval("js", "load('" + classLoader.getResource("app.js") +"')"); (3)
  }

  public static class IncludeResolver {
    public String read(String path) throws IOException, URISyntaxException {
      Path filePath = Paths.get(path);
      List<String> lines;
      File file = filePath.toFile();
      if (file.exists()) {
        lines = Files.readAllLines(filePath, StandardCharsets.UTF_8);
      } else {
        Path fileName = filePath.getFileName();
        URL url = this.getClass().getClassLoader().getResource(fileName.toString());
        if (url != null) {
          lines = Files.readAllLines(Paths.get(url.toURI()), StandardCharsets.UTF_8);
        } else {
          lines = new ArrayList<>();
        }
      }
      return String.join("\n", lines);
    }

    public String pwd() {
      return Paths.get("").toAbsolutePath().toString();
    }
  }
}

1	`IncludeResolver` 类将在使用 `include::` 指令时用于读取文件内容。
2	确保 `asciidoctor.js` 和 `app.js` 文件在应用程序的类路径中可用。

GraalVM 提供的全局 load 方法的 source 属性可以是以下类型：

字符串：源文件的路径或要执行的 URL。
java.lang.URL：查询 URL 以执行源代码。
java.io.File：读取文件以执行源代码。

接下来是什么？

现在 Asciidoctor.js 已安装，您可以开始快速浏览。