Use an Include File Multiple Times

A document can include the same file any number of times. The problem comes if there are IDs in the included file; the output document (HTML or DocBook) will then have duplicate IDs which will make it not well-formed. To fix this, you can reference a dynamic variable from the primary document in the ID.

For example, let’s say you want to include the same subsection describing a bike chain in both the operation and maintenance chapters:

= Bike Manual

:chapter: operation
== Operation

include::fragment-chain.adoc[]

:chapter: maintenance
== Maintenance

include::fragment-chain.adoc[]

Write fragment-chain.adoc as:

[id=chain-{chapter}]
=== Chain

See xref:chain-{chapter}[].

The first time the fragment-chain.adoc file is included, the ID of the included section resolves to chain-operation. The second time the file included, the ID resolves to chain-maintenance.

In order for this to work, you must use the long-hand forms of both the ID assignment and the cross reference. The single quotes around the variable name in the assignment are required to force variable substitution (aka interpolation).