如何使用spring-asciidoctor-backends

本篇内容主要讲解“如何使用spring-asciidoctor-backends”，感兴趣的朋友不妨来看看。本文介绍的方法操作简单快捷，实用性强。下面就让小编来带大家学习“如何使用spring-asciidoctor-backends”吧!

功能亮点

• Spring 官方出品, 使用方便

• 响应式设计, 支持电脑/手机移动端

• 暗黑模式

• Tabs / Code Folding / Code Chomping 等其他拓展功能

Asciidoc 简介

Use AsciiDoc for document markup. Really. It's actually readable by humans, easier to parse and way more flexible than XML. — Linus Torvalds

简单来说, Asciidoc 可以理解成加强版的 Markdown.

Asciidoctor 负责解析 Asciidoc 文档, 并最终生成 HTML 5, DocBook 5, manual pages, PDF, and EPUB 3 等格式的文档.

它拥有自动 TOC, 复杂表格(单元格合并), cross references 跨文章 anchor 引用, 脚注, Document Attributes 文档变量等等功能.

在 Java 项目中使用 Asciidoc, 可以更好地使文档文件和代码文件结合, 通过 Asciidoctor Maven/Gradle 插件, 可以更好地和 CI/CD 整合.

Getting Started

以 Gradle 项目为例, 具体参数参考 spring-asciidoctor-backends 文档 和 Asciidoctor Gradle Plugin 文档

添加 Asciidoctor 插件

plugins {   id 'java'   id 'java-library'   id 'org.asciidoctor.jvm.convert' version '3.3.0'   id 'org.asciidoctor.jvm.pdf' version '3.3.0'   id 'org.asciidoctor.jvm.epub' version '3.3.0' }

添加 spring repo

截止到目前, spring-asciidoctor-backends 还在 spring milestone 仓库中

repositories {   maven { url 'https://maven.aliyun.com/repository/central' }   mavenCentral()   maven {     url "https://repo.spring.io/milestone"   }   maven {     url "https://repo.spring.io/release"   } }

配置 asciidoctorExtensions

ext {   indexFileName = 'index.adoc'   springAsciidoctorVersion = '0.0.1-M1' } configurations {   asciidoctorExtensions } dependencies {   asciidoctorExtensions "io.spring.asciidoctor.backends:spring-asciidoctor-backends:${springAsciidoctorVersion}" }

配置 asciidoctor task

asciidoctor {   baseDirFollowsSourceDir()   sources {     include project.ext.indexFileName   }   resources {     from(sourceDir) {       include 'images/**'     }   }   outputDir file("$buildDir/asciidoc")   configurations "asciidoctorExtensions"   outputOptions {     backends "spring-html"   } }

• 其中 sources {} 配置需要转换的文件, 可自行调整

替换 html 文档 logo

目前默认 logo 为 Spring 且无法直接配置修改, 见 issue

我们可以通过 Gradle task, 打包后进行图片的替换

• 添加自己的 svg 图片, src/docs/asciidoc/images/banner-logo.svg

• 配置 Gradle 进行图片替换

asciidoctor.doLast {   delete file("$buildDir/asciidoc/img/banner-logo.svg")   copy {     from file("$buildDir/asciidoc/images/banner-logo.svg")     into file("$buildDir/asciidoc/img")   } }

配置 pdf 输出

• 下载 ttf 字体, 使用了 Sarasa-Gothic 更纱黑体 和 JetBrainsMono 字体

  放到 src/docs/asciidoc/fonts 目录

• 自定义 pdf theme src/docs/asciidoc/themes/sc-theme.yml

• 文档中添加 pdf 相关文档参数, 其中 :pdf-theme: sc 与 sc-theme.yml 名字对应

:pdf-theme: sc :pdf-fontsdir: fonts :pdf-themesdir: themes

• 配置 asciidoctorPdf task

asciidoctorPdf {   baseDirFollowsSourceDir()   sources {     include project.ext.indexFileName   }   resources {     from(sourceDir) {       include 'images/**'     }   }   outputDir file("$buildDir/asciidoc") }

打包

• 自定义 task, 打包资源

task tarIndexPage(type: Tar) {   description '打包 html 及 pdf'        dependsOn asciidoctor, asciidoctorPdf        archiveFileName = "index.tar.gz"   destinationDirectory = file("$buildDir/dist")   compression = Compression.GZIP        from "$buildDir/asciidoc" }

• 打包

./gradlew clean tarIndexPage

到此，相信大家对“如何使用spring-asciidoctor-backends”有了更深的了解，不妨来实际操作一番吧！这里是亿速云网站，更多相关内容可以进入相关频道进行查询，关注我们，继续学习！