sphinxcontrib-blockdiag is a Sphinx extension for embedding blockdiag diagrams. You can embed block diagrams with the blockdiag directive.

.. blockdiag::

    blockdiag admin {
      top_page -> config -> config_edit -> config_confirm -> top_page;


You can get archive file at http://bitbucket.org/birkenfeld/sphinx-contrib/


$ pip install sphinxcontrib-blockdiag

Configure Sphinx

To enable this extension, add sphinxcontrib.blockdiag module to extensions option at conf.py.

# Enabled extensions
extensions = ['sphinxcontrib.blockdiag']

# Fontpath for blockdiag (truetype font)
blockdiag_fontpath = '/usr/share/fonts/truetype/ipafont/ipagp.ttf'


If you write documents including multibyte characters, you have to set fontpath to blockdiag_fontpath.


.. blockdiag:: [filename]

This directive inserts a block diagram into the document. When the filename argument is specified, the extension reads the diagram definition from the specified file. Otherwise, it reads the diagram definition from the code block.


.. blockdiag:: foobar.diag

.. blockdiag::

   blockdiag {
      // some diagrams are here.

In addition, the following options are recognized:

alt : text
Alternate text: a short description of the diagram, displayed by applications that cannot display diagram.
height : length
The desired height of the diagram. When the “scale” option is also specified, they are combined. For example, a height of 200px and a scale of 50 is equivalent to a height of 100px with no scale.
width : length
The width of the diagram. As with “height” above, when the “scale” option is also specified, they are combined.
scale : integer percentage
The uniform scaling factor of the image. The default is “100%”, i.e. no scaling.
maxwidth : length

Deprecated since version 1.4.0: Use width option.

Same as “width” option.

align : “left”, “center” or “right”
The horizontal alignment of the diagram.
caption : text
The caption of the diagram.
desctable :

Description Table: a table that describes each diagram elements (cf. nodes, edges) When this option is specified, Sphinx generates Description Table from diagram, corrects descriptons from description attribute of each node and edges.


.. blockdiag::

   blockdiag {
      A -> B -> C;
      A [description = "browsers in each client"];
      B [description = "web server"];
      C [description = "database server"];


Name Description
A browsers in each client
B web server
C database server
figwidth : “image”, length
The width of the figure. A special value of “image” is allowed, in which case the included diagram’s actual width is used.
figclass : text
Set a classes attribute value on the figure element.
name : text
Set a names attribute value on the diagram-image element. This allows hyperlink references to the diagram using text as reference name.
class : text
Set a classes attribute value on the diagram-image element.

Configuration File Options

blockdiag_fontpath = str or list of str

The paths to truetype fonts. blockdiag_fontpath option accepts both single path string and list of paths.

New in version 0.1.1: blockdiag_fontpath accepts fontpath list

blockdiag_fontmap = str

The path to fontmap definitions.

blockdiag_antialias = bool

Render diagrams in antialias mode or not.

blockdiag_transparency = bool

Render diagrams as transparency or not.

New in version 1.5.0.

blockdiag_html_image_format = "PNG" or "SVG"

The output image format at generating HTML docs.

blockdiag_latex_image_format = "PNG" or "PDF"

The output image format at generating PDF docs (through LaTeX). When a value of “PDF” is specified, you can get clear diagram images. In which case, reportlab library is required.

blockdiag_tex_image_format = "PNG" or "PDF"

Deprecated since version 1.4.0: Use blockdiag_latex_image_format option.

Same as “blockdiag_latex_image_format” option.

blockdiag_debug = bool

Enable debug mode of blockdiag.