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, you can customize the admonition.properties attribute-set. Any attributes declared in it are added to the block containing the content of the admonition element, but not the title. If you also 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 above and below the text.

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, then you need to customize the template named graphical.admonition in fo/admon.xsl. If you aren't 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>