Indent Included Content

Source code snippets from external files are often padded with a leading block indent. This leading block indent is relevant in its original context. However, once inside the documentation, this leading block indent is no longer needed.

The indent attribute

The attribute indent allows the leading block indent to be stripped and, optionally, a new block indent to be set for blocks with verbatim content (listing, literal, source, verse, etc.).

  • When indent is 0, the leading block indent is stripped

  • When indent is > 0, the leading block indent is first stripped, then the content is indented by the number of columns equal to this value.

If any line in the verbatim content is not indented, the indent attribute is effectively ignored.

If the tabsize attribute is set on the block or the document, tabs are also replaced with the number of spaces specified by that attribute, regardless of whether the indent attribute is set.

Let’s consider a source block that has included content which is indented. Only the result of the include directive is shown here to help illustrate the behavior. When the indent attribute is used on the source block in the following AsciiDoc source:

[source,ruby,indent=0]
----
    def names
      @name.split ' '
    end
----

The processor produces:

def names
  @name.split ' '
end

On the other hand, this AsciiDoc source:

[source,ruby,indent=2]
----
    def names
      @name.split ' '
    end
----

Produces:

  def names
    @name.split ' '
  end

Notice that when the indent attribute is positive, the block indentation is first removed, then readded using the specified amount.