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

你可能感兴趣的:(技术文档)