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文件

安装【Mac】

1.下载
太平洋分流下载
2.安装
3.介绍atom界面

• File 文件和项目的保存与加载，设置中心，用户自定义配置
• Edit 文件编辑的操作,文件编码格式,及行跳转等
• View 重载页面,全屏,字体大小的缩放等
• Find 都是关于查询的 ,跟Sublime text极其相似,快捷键基本一样
• Package 包,就是插件列表的集合点
• Help 帮助文档,软件更新,协议等

4.更改主题
打开Settings，在Themes页面选择即可
5.安装插件

• 直接安装
  打开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

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

安装【Mac】

1.打开终端
2.更新gem的版本
在命令行输入：sudo gem update --system
3.安装asciidoctor
在命令行输入：sudo gem install -n /usr/local/bin asciidoctor
注：/usr/bin受系统完整性保护保护，不能被任何人甚至root写入，故需要手动指定安装路径
4.查看版本，检测是否安装成功
在命令行输入：asciidoctor -v

Antora

简介

Antora可以很容易地创建文档并将其发布到web上。作为一名技术作者，您只需使用AsciiDoc (Antora的内容标记语言)编写内容。然后将这些文件组织到一个或多个内容存储库中的标准项目结构中。Antora从那里获取您的内容并将其转换为网站。

安装【winodws7】

1.准备Node环境
检测是否有node.js
打开命令行cmd，输入：node –version
如果没有返回版本信息则要去官网下载Node
官网链接
安装并配置环境变量，再检测是否安装成功

> 注：如果版本过低，可以去官网下载最新版本，然后安装覆盖原目录即可实现更新

2.开始安装antora
打开命令行cmd，输入：npm i -g @antora/cli@2.0 @antora/site-generator-default@2.0
命令解释：包名开头的@很重要。它告诉npm cli包位于antora组中。如果省略这个字符，npm将假定包名是GitHub上git存储库的名称。第二个@抵消了请求的版本号。只指定主要和次要部分，以确保您接收到最新的补丁更新。
3.检测是否安装成功
在命令行输入：antora version

安装【Mac】

1.打开终端
2.安装nvm
在命令行输入：curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.8/install.sh | bash
3.创建一个.bash_profile文件
在命令行输入：vim ~/.bash_profile
4.写入安装nvm成功后所给的脚本，wq

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"  # This loads nvm

注：写入自己产生的脚本
5.更新配置文件
在命令行输入：source ~/.bash_profile
6.查看nvm的版本，检测是否成功安装
在命令行输入：nvm --version
7.安装最新版的node.js
在命令行输入：nvm install --lts
8.安装Antora
在命令行输入：npm i -g @antora/cli@2.0 @antora/site-generator-default@2.0
9.查看版本号，检测是否安装成功
在命令行输入：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 serve@6.5.8
现在，通过将web服务器指向生成的站点的位置来启动它
serve build/site
将提供的URL粘贴到浏览器的位置栏中，以便通过本地web服务器查看站点。
6.发布到github页面
注意事项：避免站点发布到github page被删除UI相关文件内容，解决方案是将.nojekyll文件添加到已发布站点的根目录中。在将文件提交到GitHub页面之前，只需在输出目录中创建一个空的.nojekyll文件。

最后更新： 2019年08月05日 01:04

原始链接： https://www.lousenjay.top/2019/02/26/Atom+Asciidoctor+Antora环境搭建/

Lousen Jay