如何使用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”有了更深的了解，不妨来实际操作一番吧！这里是亿速云网站，更多相关内容可以进入相关频道进行查询，关注我们，继续学习！