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

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



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

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



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

[[working-with-asciidoctor-including-snippets-operation]]
==== Including multiple snippets for an operation

A macro named `operation` can be used 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 are using 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, the macro
can be used to include all of the snippets for an operation, as shown in the following
example:

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

The operation macro also supports a `snippets` attribute. The `snippets` attribute can be
used 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']
----

This 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's including using `operation`, a section with a title will be
created. Default titles are provided for the 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 table above, a default title will be generated by replacing
`-` characters with spaces and capitalising the first letter. For example, the title for a
snippet named `custom-snippet` will be "Custom snippet".

The default titles can be customized 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", use the following attribute:

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



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

The http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[include
macro] is used to include individual snippets in your documentation. The `snippets`
attribute that is automatically set by `spring-restdocs-asciidoctor` configured in the
<<getting-started-build-configuration, build configuration>> can be used to reference the
snippets output directory. For example:

[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
http://asciidoctor.org/docs/user-manual/#cols-format[formatting a table's columns]. For
example, the widths of a table's columns can be specified using the `cols` attribute:

[source,indent=0]
----
[cols="1,3"] <1>
\include::{snippets}/index/links.adoc[]
----
<1> The table's width will be 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

The title of a table can be specified using a line prefixed by a `.`:

[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. The problem can be avoided by
escaping the `|` with a backslash, i.e. by using `\|` rather than `|`.

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

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



==== Further reading

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