Skip to content

Latest commit

 

History

History
487 lines (339 loc) · 12.7 KB

README.adoc

File metadata and controls

487 lines (339 loc) · 12.7 KB

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'
}

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.

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 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

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

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,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

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

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

[[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:

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.

[[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

{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 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[].

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 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 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).