Directive Reference

needsvg Directive

Renders SVG markup with Jinja2 templating and sphinx-needs integration.

.. needsvg::
   :width: 400
   :height: 100
   :align: center
   :debug:

   <svg>
     ...Jinja2-templated SVG content...
   </svg>

Or load the SVG template from an external file:

.. needsvg::
   :file: _svgs/pipeline.svg.j2
   :debug:

Options

Option	Type	Default	Description
:file:	path		Path to an SVG/Jinja2 template file, relative to the current document. When set, the file content is used instead of the directive body. Sphinx tracks the file as a dependency and rebuilds when it changes. Works with draw.io SVG exports – see Examples for constraints on which Jinja helpers are safe to use inside drawio SVGs. When a drawio content attribute is present, Jinja expressions in cell labels are rendered and the attribute is updated in the build output.
:width:	string	100%	SVG container width
:height:	string	auto	SVG container height
:align:	choice	center	Horizontal alignment: left, center, or right
:debug:	flag		Show the raw RST/Jinja source as a code block above the rendered diagram

Jinja2 Helpers

The following helpers are available in the directive body:

needs

A dictionary of all sphinx-needs entities, keyed by ID.

{{ needs['REQ_001'].title }}
{{ needs['REQ_001'].type }}
{{ needs['REQ_001'].docname }}

ref(need_id)

Returns the URL to a need’s anchor in the documentation. Use inside SVG <a> elements:

<a href="{{ ref('REQ_001') }}">
  <text>Click me</text>
</a>

Returns #UNKNOWN-<id> if the need does not exist.

filter(expression)

Returns a list of needs matching a filter expression. Uses the same filter syntax as sphinx-needs:

{% for need in filter("type == 'req'") %}
  <text>{{ need.title }}</text>
{% endfor %}

flow(need_id)

Returns a pre-styled SVG <g> element (a card with ID and title) wrapped in a clickable <a> link. Useful for quick diagrams without hand-crafting SVG:

<svg width="200" height="60">
  {{ flow('REQ_001') }}
</svg>

The card is 120x40 pixels with rounded corners, a light blue fill, and the need’s ID and title as text.

Error Handling

If a Jinja2 template error occurs (e.g. referencing a nonexistent need with bracket notation), the build does not crash. Instead:

• A warning is logged with the source file and line number

• The SVG is replaced with a red error message

.. needsvg::

   <svg>{{ needs['NONEXISTENT'].title }}</svg>

This renders as: needsvg error: 'NONEXISTENT'