spring-asciidoctor-backends/README.adoc

= Asciidoctor Spring Backends

Alternative HTML conversion for Asciidoctor with a Spring "look and feel".


== Maven build integration
You can use the https://github.com/asciidoctor/asciidoctor-maven-plugin[Asciidoctor Maven plugin] to generate your documentation.

[source,xml]
----
<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 will probably also need to add the Spring Maven repository:

[source,xml]
----
<repositories>
	<repository>
		<id>spring-release</id>
		<name>Spring Releases</name>
		<url>https://repo.spring.io/release</url>
		<snapshots>
			<enabled>false</enabled>
		</snapshots>
	</repository>
</repositories>
----

or for milestones:

[source,xml]
----
<repositories>
	<repository>
		<id>spring-milestones</id>
		<name>Spring Milestones</name>
		<url>https://repo.spring.io/milestone</url>
		<snapshots>
			<enabled>false</enabled>
		</snapshots>
	</repository>
</repositories>
----



== Gradle build integration
You can use the https://asciidoctor.org/docs/asciidoctor-gradle-plugin/[Asciidoctor Gradle plugin] to generate your documentation.

[source,gradle]
----
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"
	}
}
----

You will probably also need to add the Spring Maven repository:

[source,gradle]
----
repositories {
	mavenCentral()
	maven {
		url "https://repo.spring.io/release"
	}
}
----

or for milestones:

[source,gradle]
----
repositories {
	mavenCentral()
	maven {
		url "https://repo.spring.io/milestone"
	}
}
----



== 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 https://spring.io[spring.io].

One minor difference between the documentation output and https://spring.io[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 https://markdotto.com/2018/02/07/github-system-fonts/[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`:

[source, asciidoctor]
----
: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 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,subs="verbatim,attributes"]
....
[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:

[source,subs="verbatim,attributes"]
....
[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,subs="verbatim,attributes"]
....
[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,subs="verbatim,attributes"]
....
[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

| `default`
| `imports` `tags`

| `all`
| Enable all folding

| `none`
| Disable all folding

| `imports`
| Fold import statements

| `tags`
| Fold `@fold:on` / `@fold:off` tags
|===

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

| `/* @chomp:line <replacement> */`
| Chomps the rest of the line and adds the replacement

| `// @chomp:file`
| Chomps the remainder of the file

| `/**/`
| Chomps the rest of the line and adds `+++...+++`
|===

For example, the following file:

[source,subs="verbatim,attributes"]
....
[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:

[source,subs="verbatim,attributes"]
....
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

| `default`
| `tags` `formatters` `suppresswarnings`

| `all`
| Enable all chomping

| `none`
| Disable all chomping

| `headers`
| Chomp any file headers (up to `package`)

| `packages`
| Chomp the package declaration or replaces it with `chomp_package_replacement`

| `tags`
| Chomp on the comment tags listed above

| `formatters`
| Chomp any `@formatter:on`/`@formatter:off` comments

| `suppresswarnings`
| Chomp any `@SuppressWarnings` annotations
|===

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;`:

[source,subs="verbatim,attributes"]
....
= My Document
:chomp_package_replacement: com.example
....



=== Anchor Rewriting
Anchor 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:

[source,asciidoctor]
----
[[initializzzing]]
== Initializing
This is how to do it.
----

You then fix the typo and publish a new revision:

[source,asciidoctor]
----
[[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:

[source,properties]
.anchor-rewrite.properties
----
initializzzing=initializing
----



=== Convention Based Code Import
Convention 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`.

[source,subs="verbatim,attributes"]
....
[[my.example-project]]
== My Example Project
include::code:SomeCode[]
....

The following languages are supported by convention based imports:

|===
| Language | Root Directory Property | Extension

| Java
| `{docs-java}`
| `.java`

| Kotlin
| `{docs-kotlin}`
| `.kt`

| Groovy
| `{docs-groovy}`
| `.grovy`
|===

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
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 https://antora.org[Antora], which https://gitlab.com/antora/antora-ui-default/-/issues/58[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:<name>[]+++` macros inside your markup, with images being resolved from the locally bundled `fontawesome.css` stylesheet.

For example:

[source,asciidoctor]
----
= Asciidoctor Font Awesome Document
:iconfont-fontawesome:

The folder icon is icon:folder[].
----



== Contributing
If you're looking to contribute to this project, or you're just trying to navigate the code please take a look at the link:CONTRIBUTING.adoc[CONTRIBUTING] file.



== License
With the exception of link:src/main/css/asciidoctor.css[`asciidoctor.css`], use of this software is granted under the terms of the https://www.apache.org/licenses/LICENSE-2.0[Apache License, Version 2.0] (Apache-2.0).
See link:LICENSE.txt[] to find the full license text.

The contents of link:src/main/css/asciidoctor.css[`src/main/css/asciidoctor.css`] have been derived from https://gitlab.com/antora/antora-ui-default/-/blob/8751b86b76d6779fbbcf0fccd58fafcf73c49260/src/css/doc.css[gitlab.com/antora/antora-ui-default CSS] and as such use of this file alone is granted under the terms of the https://www.mozilla.org/en-US/MPL/2.0/[Mozilla Public License Version 2.0] (MPL-2.0).