Atom+Asciidoctor+Antora环境搭建
个人博客原文链接
Atom
简介
Atom是github专门为程序员推出的一个跨平台文本编辑器。具有简洁和直观的图形用户界面，并有很多有趣的特点：支持CSS，HTML，JavaScript等网页编程语言。它支持宏，自动完成分屏功能，集成了文件管理器。
安装【windows7】
1.下载
官网链接
2.安装
3.配置环境变量
path中添加C:\Users\Administrator\AppData\Local\atom\bin
4.检测环境变量是否配置成功
5.打开cmd，使用apm命令查看
6.介绍atom界面
- File 文件和项目的保存与加载，设置中心，用户自定义配置
- Edit 文件编辑的操作,文件编码格式,及行跳转等
- View 重载页面,全屏,字体大小的缩放等
- Find 都是关于查询的 ,跟Sublime text极其相似,快捷键基本一样
- Package 包,就是插件列表的集合点
- Help 帮助文档,软件更新,协议等
7.更改主题
打开Settings，在Themes页面选择即可
8.安装插件
- 直接安装
打开Settings，在Install页搜索插件名称，点击Install即可 - 通过git手动安装
打开Settings，在Install页搜索插件名称
点入插件介绍找到github地址
打开git切换到packages目录C:\Users\Administrator\AppData\Local\atom\packages
输入指令git clone https://github.com/emmetio/emmet-atom.git
切换到安装的插件文件夹cd emmet-atom
开始安装npm install
重启Atom
9.自定义快捷键
File -> 打开keymap.cson文件
Asciidoctor
简介
Asciidoctor是一个快速的文本处理器和发布工具链，用于将AsciiDoc内容转换为HTML5、EPUB3、PDF、DocBook 5(或4.5)slidedeck等格式。Asciidoctor是用Ruby编写的，打包为RubyGem并发布到(RubyGems.org)。gem还打包在几个Linux发行版中，包括Fedora、Debian和Ubuntu。
安装【windows7】
1.准备Ruby环境
下载安装并配置环境变量【若勾选自动添加到path则可略过】
下载链接
检测是否安装成功
在命令行输入：ruby -v
2.安装asciidoctor
在命令行输入：gem install asciidoctor
3.检测是否安装成功
在命令行输入：asciidoctor --version
4.如果需要绘制图表，还需要安装asciidoctor-diagram
在命令行输入：gem install asciidoctor-diagram
5.从asciidoc文档生成html文档（DEMO）
在命令行输入：asciidoctor -r asciidoctor-diagram xxx.adoc
Antora
简介
Antora可以很容易地创建文档并将其发布到web上。作为一名技术作者，您只需使用AsciiDoc (Antora的内容标记语言)编写内容。然后将这些文件组织到一个或多个内容存储库中的标准项目结构中。Antora从那里获取您的内容并将其转换为网站。
安装【winodws7】
1.准备Node环境
检测是否有node.js
打开命令行cmd，输入：node --version
如果没有返回版本信息则要去官网下载Node
官网链接
安装并配置环境变量，再检测是否安装成功
> 注：如果版本过低，可以去官网下载最新版本，然后安装覆盖原目录即可实现更新
2.开始安装antora
打开命令行cmd，输入：npm i -g @antora/[email protected] @antora/[email protected]
命令解释：包名开头的@很重要。它告诉npm cli包位于antora组中。如果省略这个字符，npm将假定包名是GitHub上git存储库的名称。第二个@抵消了请求的版本号。只指定主要和次要部分，以确保您接收到最新的补丁更新。
3.检测是否安装成功
在命令行输入：antora version
简单的使用流程
1.选择一个剧本
要创建文档站点，Antora需要一个剧本。但首先，您需要创建或选择一个目录，在其中存储剧本，并保存生成的站点文件(假设使用默认输出配置)。
a.打开终端并创建一个名为demo-site的新目录。
mkdir demo-site
b.进入到该目录中
cd demo-site
c.使用文本编辑器或IDE，创建一个名为site的新剧本文件。用下面示例的内容填充它。
site.yml
site:
title: Antora Demo Site
url: https://example.org/docs
start_page: component-b::index.adoc
content:
sources:
- url: https://gitlab.com/antora/demo/demo-component-a.git
branches: master
- url: https://gitlab.com/antora/demo/demo-component-b.git
branches: [v2.0, v1.0]
start_path: docs
ui:
bundle:
url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/master/raw/build/ui-bundle.zip?job=bundle-stable
snapshot: true
注：404页面和站点地图文件仅在站点生成时生成。设置url属性。
注：该网站。site.start_page属性接受与xref中使用的相同的页ID语法。
d.将site.yml剧本作为站点保存
2.运行Antora
a.要使用默认的Antora站点生成器生成站点，请将Antora命令指向您的playbook文件。在终端输入命令
antora site.yml
> 注：首先，Antora将克隆内容存储库。终端显示每个存储库的克隆进度。克隆完成后，Antora将AsciiDoc页面转换为可嵌入的HTML，在UI页面模板中包装HTML，然后将这些页面组装到目标文件夹下的站点中，默认构建目录bulid/site/。
b.当命令提示符($)重新出现在终端时，Antora已经运行完成。
c.切换到站点文件夹(cd)并列出其内容。
cd build/site/
ls -l
然后你将看到以下文件或目录列表
_ 404.html component-a component-b index.html sitemap-component-a.xml sitemap-component-b.xml sitemap.xml
> 注：如果站点不存在，404.html和sitemap文件将丢失。剧本中没有定义site.url属性。主sitemap文件实际上是一个sitemap索引。该文件链接到每个组件的sitemap，在这里可以找到各个页面的URL。
d.在某些操作系统上，可以通过输入open和HTML文件的名称，直接从命令行打开站点。
open index.html
> 注：或者可以直接通过build/site/index.html打开站点
3.缓存
a.当Antora第一次运行时，它将在缓存目录中缓存资源。Antora缓存两种类型的资源:克隆的git存储库和UI包下载。
b.如果您想完全清除缓存，您需要找到系统上的Antora缓存目录并删除它。
4.私人git仓库
a.Antora支持通过SSH或HTTP/HTTPS来连接私有仓库。 b.如果剧本被配置为通过SSH获取私有存储库，那么您必须运行具有标识的SSH代理(即您已经链接到git主机上的帐户。如果SSH代理没有运行，或者您的密钥和帐户不匹配，Antora在尝试克隆私有存储库时将失败。
5.本地预览
a.因为Antora生成静态站点，所以不需要为了预览站点而将站点发布到服务器,可以直接通过build/site/index.html打开站点
b.也可以在本地服务器上运行，需要先使用npm全局安装服务包
npm i -g [email protected]
现在，通过将web服务器指向生成的站点的位置来启动它
serve build/site
将提供的URL粘贴到浏览器的位置栏中，以便通过本地web服务器查看站点。
6.发布到github页面
注意事项：避免站点发布到github page被删除UI相关文件内容，解决方案是将.nojekyll文件添加到已发布站点的根目录中。在将文件提交到GitHub页面之前，只需在输出目录中创建一个空的.nojekyll文件。