asciidoctor ghpages action

asciidoctor github页面动作

GitHub动作，该动作在CI工作流程中构建Asciidoc github页面。它递归地将每个adoc文件转换为html ，将结果README.html重命名为index.html然后将所有生成的HTML和现有文件推到gh-pages分支。如果您不需要像安托拉（Antora）这样的幻想，那么此操作可能是发布一个简单的Asciidoc网站的方法。但是，如果您需要一个更具结构化的网站，那么Jekyll Asciidoc Quickstart适合您。

配置操作后，您的github页面将在http://your-username.github.io/your-repository上找到。

配x	请记住，每次执行操作时， gh-pages分支都会消失。如果您手动添加任何内容，在CI工作流程之外，内容将丢失。

1。现场演示

我们通过将此存储库发布到GitHub页面来品尝自己的药物。

2。配置

您只需要将操作添加到YML工作流文件中，仅此而已。您可以选择通过为操作提供额外的参数来自定义构建，该参数将交给Asciidoctor工具。

您可以在此处查看完整的工作流文件。如果您不想使用github操作接口，而只需将该文件复制到存储库中的同一位置，则可以开箱即用。

2.1。故障排除

如果您获得错误“远程：拒绝Github-actions [bot]的权限”，请访问Settings > Actions > General ，然后选择Read and write permissions 。

2.2。构建电子书

该操作允许从ASCIIDOC文件自动生成ebook.pdf文件。 PDF也被推到gh-pages分支。为此，只需添加以下配置：

 pdf_build : true

可以在此处提供示例PDF电子书。

2.3。 Asciidoctor Reles.js幻灯片

您还可以通过此操作构建Asciidoctor Releve.js滑动。这将生成gh-pages 。您可以对此使用以下配置：

• slides_build: boolean启用构建slide.html文件（默认为false）

• slides_main_adoc_file: string - 定义assiidoc源文件的名称以构建幻灯片（默认的'readme'）。不包括文件扩展名。

• slides_skip_asciidoctor_build: boolean如果您只想生成幻灯片（默认为false），请使用asciidoctor命令启用常规HTML文件的构建

3。其他例子

如果您想检查如何从多个ASCIIDOC文档创建网站，请检查此示例存储库。它仅在葡萄牙语中，但是您可以得到结构。

4。动作的工作方式

该操作很简单，但是要展示如何创建一个来自不同ASCIIDOC文件的多个页面的网站，请在此处单独的页面中提供详细信息。并实现上面的链接指向A：（i）从GitHub存储库打开此页面时的adoc文件，以及（ii）从GitHub页面打开此页面时的html文件。

5。常见问题解答

5.1。如何配置自定义域？

GitHub页面需要在gh-pages上的CNAME文件。但是在每次动作运行中， gh-pages分支都被抹去了。要使自定义域工作，只需在main或master分支的根目录中添加CNAME文件，它将自动复制到gh-pages分支。如果您配置了source_dir ，则必须在您配置的source_dir内部使用CNAME文件。