如何使用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”有了更深的了解，不妨來實際操作一番吧！這里是億速云網站，更多相關內容可以進入相關頻道進行查詢，關注我們，繼續學習！