Alternative HTML conversion for Asciidoctor with a Spring "look and feel".
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>You can use the Asciidoctor Gradle plugin to generate your documentation.
plugins {
id 'org.asciidoctor.jvm.convert' version '3.1.0'
}
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"
}
}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.
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.
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.
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.) |
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.
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.
Tab support is included in the site Javascript and can be used without needing the spring-asciidoctor-extensions-block-switch extension.
The Javascript 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 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 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 |
|
Chomp any |
|
Chomp any |
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.exampleAnchor rewriting can be used if you need to evolve a document and change previously published anchor links.
For example, say you publish a document with the following typo:
[[initializzzing]]
== Initializing
This is how to do it.You then fix the typo and publish a new revision:
[[initializing]]
== Initializing
This is how to do it.You can add a rewrite rule so that any links to https://example.com/doc#initializzzing will be automatically changed to https://example.com/doc#initializing.
To define the rewrite rules, add a anchor-rewrite.properties file to your base_dir (usually the same directory as your index.adoc file).
For example, the following file would be used in the example above:
initializzzing=initializingConvention based code imports allows you to quickly import code snippets from package names that are constructed using the section ID.
For example, the following .adoc file will try to import the Java file {docs-java}/my/exampleproject/SomeCode.java.
[[my.example-project]]
== My Example Project
link:code:SomeCode[role=include]The following languages are supported by convention based imports:
| Language | Root Directory Property | Extension |
|---|---|---|
Java |
|
|
Kotlin |
|
|
Groovy |
|
|
If more than one language file is found then tabs will automatically be created to allow the user to see all the examples. An exception will be raised if no files are found.
The package name is constructed by removing all - characters from the section ID and replacing all .’s with `/.
Font Awesome support is available in the standard Asciidoctor HTML 5 backend, however, it is not available by default in this backend. This is to align with Antora, which doesn’t currently support Font Awesome.
If you want to enable Font Awesome 4 support in your documents you can set the iconfont-fontawesome attribute.
This will allow you to use icon:[] macros inside your markup, with images being resolved from the locally bundled fontawesome.css stylesheet.
For example:
= Asciidoctor Font Awesome Document
:iconfont-fontawesome:
The folder icon is icon:folder[].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.
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 have 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).