[[working-with-asciidoctor]]
== Working with Asciidoctor

This section describes the aspects of working with Asciidoctor that are particularly
relevant to Spring REST Docs.

NOTE: Asciidoc is the document format. Asciidoctor is the tool that produces content
(usually as HTML) from Asciidoc files (which end with `.adoc`).



[[working-with-asciidoctor-resources]]
=== Resources

 * https://asciidoctor.org/docs/asciidoc-syntax-quick-reference[Syntax quick reference]
 * https://asciidoctor.org/docs/user-manual[User manual]



[[working-with-asciidoctor-including-snippets]]
=== Including Snippets

This section covers how to include Asciidoc snippets.

[[working-with-asciidoctor-including-snippets-operation]]
==== Including Multiple Snippets for an Operation

You can use a macro named `operation` to import all or some of the snippets that have
been generated for a specific operation. It is made available by including
`spring-restdocs-asciidoctor` in your project's <<getting-started-build-configuration,
build configuration>>.

WARNING: If you use Gradle and its daemon or support for continuous builds, do not
use version 1.5.6 of the `org.asciidoctor.convert` plugin. It contains a
https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/222[regression] that
prevents extensions from working reliably.

The target of the macro is the name of the operation. In its simplest form, you can use
the macro to include all of the snippets for an operation, as shown in the following
example:

====
[source,indent=0]
----
operation::index[]
----
====

You can use the operation macro also supports a `snippets` attribute. The `snippets`
attribute to select the snippets that should be included. The attribute's value is a
comma-separated list. Each entry in the list should be the name of a snippet file (minus
the `.adoc` suffix) to include. For example, only the curl, HTTP request and HTTP response
snippets can be included, as shown in the following example:

====
[source,indent=0]
----
operation::index[snippets='curl-request,http-request,http-response']
----
====

The preceding example is the equivalent of the following:

====
[source,adoc,indent=0]
----
[[example_curl_request]]
== Curl request

\include::{snippets}/index/curl-request.adoc[]

[[example_http_request]]
== HTTP request

\include::{snippets}/index/http-request.adoc[]

[[example_http_response]]
== HTTP response

\include::{snippets}/index/http-response.adoc[]

----
====

[[working-with-asciidoctor-including-snippets-operation-titles]]
===== Section Titles

For each snippet that is included by using the `operation` macro, a section with a title
is created. Default titles are provided for the following built-in snippets:

|===
| Snippet | Title

| `curl-request`
| Curl Request

| `http-request`
| HTTP request

| `http-response`
| HTTP response

| `httpie-request`
| HTTPie request

| `links`
| Links

| `request-body`
| Request body

| `request-fields`
| Request fields

| `response-body`
| Response body

| `response-fields`
| Response fields
|===

For snippets not listed in the preceding table, a default title is generated by replacing
`-` characters with spaces and capitalizing the first letter. For example, the title for a
snippet named `custom-snippet` `will be` "`Custom snippet`".

You can customize the default titles by using document attributes. The name of the
attribute should be `operation-{snippet}-title`. For example, to customize the title of
the `curl-request` snippet to be "Example request", you can use the following attribute:

====
[source,indent=0]
----
:operation-curl-request-title: Example request
----
====



[[working-with-asciidoctor-including-snippets-individual]]
==== Including Individual Snippets

The https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[include
macro] is used to include individual snippets in your documentation. You can use the
`snippets` attribute (which is automatically set by `spring-restdocs-asciidoctor`
configured  in the <<getting-started-build-configuration, build configuration>>) to
reference the snippets output directory. The following example shows how to do so:

====
[source,indent=0]
----
\include::{snippets}/index/curl-request.adoc[]
----
====



[[working-with-asciidoctor-customizing-tables]]
=== Customizing Tables

Many of the snippets contain a table in its default configuration. The appearance of the
table can be customized, either by providing some additional configuration when the
snippet is included or by using a custom snippet template.



[[working-with-asciidoctor-customizing-tables-formatting-columns]]
==== Formatting Columns

Asciidoctor has rich support for
https://asciidoctor.org/docs/user-manual/#cols-format[formatting a table's columns]. As
the following example shows, you can specify the widths of a table's columns by using the
`cols` attribute:

====
[source,indent=0]
----
[cols="1,3"] <1>
\include::{snippets}/index/links.adoc[]
----
<1> The table's width is split across its two columns, with the second column being three
	times as wide as the first.
====



[[working-with-asciidoctor-customizing-tables-title]]
==== Configuring the Title

You can specify the title of a table by using a line prefixed by a `.`.
The following example shows how to do so:

====
[source,indent=0]
----
.Links <1>
\include::{snippets}/index/links.adoc[]
----
<1> The table's title will be `Links`.
====



[[working-with-asciidoctor-customizing-tables-formatting-problems]]
==== Avoiding Table Formatting Problems

Asciidoctor uses the `|` character to delimit cells in a table. This can cause problems
if you want a `|` to appear in a cell's contents. You can avoid the problem by
escaping the `|` with a backslash -- in other words, by using `\|` rather than `|`.

All of the default Asciidoctor snippet templates perform this escaping automatically by
using a Mustache lamba named `tableCellContent`. If you write your own custom templates
you may want to use this lamba. The following example shows how to escape `|` characters
in a cell that contains the value of a `description` attribute:

====
----
| {{#tableCellContent}}{{description}}{{/tableCellContent}}
----
====



==== Further Reading

See the https://asciidoctor.org/docs/user-manual/#tables[Tables section of the
Asciidoctor user manual] for more information about customizing tables.
