Asciidoctor Spring Backends
Alternative HTML conversion for Asciidoctor with a Spring "look and feel".
Maven build integration
You can use the Asciidoctor Maven plugin to generate your documentation.
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>2.1.0</version>
<executions>
<execution>
<id>generate-html-documentation</id>
<phase>prepare-package</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>spring-html</backend>
</configuration>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>io.spring.asciidoctor.backends</groupId>
<artifactId>spring-asciidoctor-backends</artifactId>
<version>${spring-asciidoctor-backends.version}</version>
</dependency>
</dependencies>
</plugin>
Gradle build integration
You can use the Asciidoctor Gradle plugin to generate your documentation.
plugins {
id 'org.asciidoctor.jvm.convert' version '3.1.0'
}
repositories {
mavenCentral()
maven {
url "https://repo.spring.io/release"
}
}
configurations {
asciidoctorExtensions
}
dependencies {
asciidoctorExtensions "io.spring.asciidoctor.backends:spring-asciidoctor-backends:${spring-asciidoctor-backends.version}"
}
asciidoctor {
configurations "asciidoctorExtensions"
sourceDir "src/asciidoc"
outputOptions {
backends "spring-html"
}
}
Features
Spring Look and Feel
Spring specific stylesheets and javascript are produced with each HTML file that provides a Spring "look and feel". As much as possible, styling mirrors the look of spring.io.
One minor difference between the documentation output and spring.io is the choice of fonts. Since documentation tends to contain more content, we use system default fonts rather than "Metropolis" or "Open Sans". This aligns with GitHub’s font choice and tends to produce better results then using a custom font.
Responsive Design
Generated HTML includes responsive selectors that mean it should work well across a range of devices. We specifically optimize for desktop, tablet (both horizontal and vertical orientation) and smartphone.
Graceful Javascript Degradation
Documentation pages generated by this backend should render correctly even if Javascript has been disabled. Some features will not appear if the user has disabled Javascript.
"Back to Index" Link
For HTML output, if the current page is not index.html, you automatically get a link to index.html. This link appears above the table of contents. For many projects, this link never appears, because that project’s build renders the documentation as index.html.
You can customize the destination of the "Back to Index" link by specifying a index-link attribute in your document. For example, the following attribute would link to https://spring.io:
:index-link: https://spring.io|
Note
|
Please do use a link that readers might reasonably think would be an index page. (The canonical case is the project’s page on spring.io.) |
Dark Mode
A "dark mode" switcher is included at the top of each page. By default the theme will match the users system preferences, but it can be switched easily. Dark mode settings are saved using local storage so that the user doesn’t need to change them on each reload.
Copy to Clipboard
Code blocks have an additional "Copy to clipboard" button that appears when the user hovers over the block. The unfolded (see below) version of the code text is always used when copying to the clipboard.
Tabs
Tab support is included in the site Javascript and can be used without needing the spring-asciidoctor-extensions-block-switch extension. The Javascipt post-processes Asciidoctor’s HTML output to collapse multiple blocks into one and provides tabs that can be used to switch between them.
To use tabs, one block must have the role="primary" attribute, and one or more blocks must have a role="secondary" attribute. The tabs are named using the block titles.
For example:
[source,xml,indent=0,role="primary"]
.Maven
----
<dependency>
<groupId>com.example</groupId>
<artifactId>some-library</artifactId>
<version>1.2.3</version>
</dependency>
----
[source,indent=0,role="secondary"]
.Gradle
----
compile 'com.example:some-library:1.2.3'
----You can also use blocks for more complex markup:
[primary]
.Maven
--
[source,xml,indent=0]
----
<dependency>
<groupId>com.example</groupId>
<artifactId>some-library</artifactId>
<version>1.2.3</version>
</dependency>
----
TIP: XML uses angle brackets.
--
[secondary]
.Gradle
--
I can write things here.
[source,indent=0]
----
compile 'com.example:some-library:1.2.3'
----
--Code Folding
Code folding allows non-pertinent sections of code to be hidden away for the majority of the time. The user can click on an "unfold code" button if they want to see the full code.
Code folding is particularly useful when code samples have been externalized. There’s often details needed to make the compiler happy that aren’t all that relevant to the documentation.
By default, all java imports will be automatically folded. Additional "fold" sections can also be defined using special @fold:on and @fold:off comments.
For example, the following Java file will fold-away the fields:
[source,java]
----
public class Example {
// @fold:on
private final String first;
private final String second;
// @fold:off
public Example(String first, String second) {
this.first = first;
this.second = second;
}
}
----You can also include replacement text that will be displayed when the code is folded. For example, the following Java file will show a // getters / setters... comment when the code is folded:
[source,java]
----
public class Example {
private String first;
private String second;
// @fold:on // getters / setters...
public String getFirst() {
return this.first;
}
public void setFirst(String first) {
this.first = first;
}
public String getSecond() {
return this.second;
}
public void setSecond(String second) {
this.second = second;
}
// @fold:off
}
----You can use the fold attribute if you want change the default settings. The attribute can be used on the document or the block. The attribute value is a space delimited list containing one or more of the following flags:
| Flag | Description |
|---|---|
|
|
|
Enable all folding |
|
Disable all folding |
|
Fold import statements |
|
Fold |
You can prefix the flag with + or - at the block level if you want to override a document setting.
Code Chomping
Code chomping allows specific parts of a Java code block to be removed. It’s mainly useful if you have externalized code files with details that are only required to make the compiler happy.
By default, chomping will remove parts of the code that match specific comments as well as @formatter:on/@formatter:off comments. You can also turn on addition chomping for headers, packages
The following chomp comments are supported:
| Comment | Description |
|---|---|
|
Chomps the rest of the line and adds the replacement |
|
Chomps the remainder of the file |
|
Chomps the rest of the line and adds |
For example, the following file:
[source,java]
----
public class Example {
private final Something something;
private final Other other;
public Example() {
this.something = /**/ new MockSomething();
this.other = /* @chomp:line ... your thing */ new MyThing();
}
}
----Will be rendered as:
public class Example {
private final Something something;
private final Other other;
public Example() {
this.something = ...
this.other = ... your thing
}
}You can use the chomp attribute if you want change the default settings. The attribute can be used on the document or the block. The attribute value is a space delimited list containing one or more of the following flags:
| Flag | Description |
|---|---|
|
|
|
Enable all chomping |
|
Disable all chomping |
|
Chomp any file headers (up to |
|
Chomp the package declaration or replaces it with |
|
Chomp on the comment tags listed above |
You can prefix the flag with + or - at the block level if you want to override a document setting.
The chomp_package_replacement attribute can be set on the block or the document if you want to replace the package rather than remove it. For example, the following document will replace all package declarations with package com.example;:
= My Document
:chomp_package_replacement: com.exampleContributing
If you’re looking to contribute to this project, or you’re just trying to navigate the code please take a look at the CONTRIBUTING file.
License
With the exception of asciidoctor.css, use of this software is granted under the terms of the Apache License, Version 2.0 (Apache-2.0). See LICENSE.txt to find the full license text.
The contents of src/main/css/asciidoctor.css as been derived from gitlab.com/antora/antora-ui-default CSS and as such use of this file alone is granted under the terms of the Mozilla Public License Version 2.0 (MPL-2.0).
24.8k Jan 6, 2023
1 Sep 12, 2022
1.1k Nov 27, 2022
7 Oct 3, 2022
65 Dec 23, 2022
4.5k Dec 30, 2022
2 Feb 8, 2022
20 Sep 17, 2022
43 Dec 22, 2022
2 Jan 9, 2022
0 Mar 16, 2022
6 May 1, 2022
4 Sep 3, 2022
2 Jul 11, 2022
10 Nov 27, 2022
15.7k Dec 31, 2022
19 Sep 23, 2022
11 Apr 11, 2022
7 Dec 20, 2022