Admonitions in DocBook include the note, caution, warning, tip, and important elements. They share the same DocBook templates so that their output styles are similar. You can do some customization using just stylesheet parameters, as described in the section “Admonition graphics”. But if you want to do more extensive changes, you will need to customize some templates.

If all you are doing is customizing the admonition graphics, that is easily done. When you create your admonition image files, just name them after the corresponding DocBook element, for example note.png. If you are using a different file format, then use the admon.graphics.extension parameter to indicate the new filename extension. You may also need to use the admon.graphics.path parameter to indicate the location of your graphics files so the XSL-FO processor can find them and merge them into the PDF output.

If your image files are larger or smaller than the stock image files, then you can customize the template in admon.graphic.width mode that sets the graphic width. This is a template mode, not a parameter, and the templates should return a width value. Because it is a mode, you can have a different template for each admonition element to support different image widths. For example:

<xsl:template match="note" mode="admon.graphic.width">
  <xsl:text>24pt</xsl:text>
</xsl:template>

<xsl:template match="*" mode="admon.graphic.width">
  <xsl:text>32pt</xsl:text>
</xsl:template>

With this customization, the image for a note element gets a 24pt width, and all the other admonition elements get a 32pt width (the default is 36pt). For HTML output, there is a similar template mode for adjusting image widths.

If you want to change the typography for admonitions, there are several attribute-sets you can customize. The outermost fo:block containing the entire admonition (title, graphic, text) can be customized using either the graphical.admonition.properties or nongraphical.admonition.properties attribute-set, whichever style you are using (selected by the admon.graphics parameter). Use either of these attribute-sets to establish spacing, indents, font changes, borders, or background color for the entire admonition.

The admonition.properties attribute-set is applied to the text content, not including any title or graphic. Any attributes declared in it are added to the block containing the content of the admonition element, but not the title.

If you want to customize the title typography, you can use the admonition.title.properties attribute-set. These attribute sets can also be used to change the indents and spacing around the title.

If these methods are not sufficient for your needs, then you can customize the template that formats the admonition. If you have the admon.graphics parameter set to 1, then you need to customize the template named graphical.admonition in fo/admon.xsl. If you are not using graphical admonitions, then customize the template named nongraphical.admonition instead. For example, the following customization draws rule lines above and below each admonition:

<xsl:template name="nongraphical.admonition">
  <xsl:variable name="id">
    <xsl:call-template name="object.id"/>
  </xsl:variable>

  <fo:block space-before.minimum="0.8em"
            space-before.optimum="1em"
            space-before.maximum="1.2em"
            start-indent="0.25in"
            end-indent="0.25in"
            border-top="0.5pt solid black"
            border-bottom="0.5pt solid black"
            padding-top="4pt"
            padding-bottom="4pt"
            id="{$id}">
    <xsl:if test="$admon.textlabel != 0 or title">
      <fo:block keep-with-next='always'
                xsl:use-attribute-sets="admonition.title.properties">
         <xsl:apply-templates select="." mode="object.title.markup"/>
      </fo:block>
    </xsl:if>

    <fo:block xsl:use-attribute-sets="admonition.properties">
      <xsl:apply-templates/>
    </fo:block>
  </fo:block>
</xsl:template>