导航：首页 > 开发技术 >

如何使用spring-asciidoctor-backends

发表于：2024-11-14 作者：千家信息网编辑

千家信息网最后更新 2024年11月14日，本篇内容主要讲解"如何使用spring-asciidoctor-backends"，感兴趣的朋友不妨来看看。本文介绍的方法操作简单快捷，实用性强。下面就让小编来带大家学习"如何使用spring-asc

千家信息网最后更新 2024年11月14日如何使用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"}