The Template API

While the document and element APIs are available for folks who are already somewhat familiar with Markdown, a template system is slowly being developed for folks who are looking for a bit more convenience. Ultimately, these folks can expect support for typical document sections such as tables of contents, footers, copyrights, and more.

Template Interface

To allow for templates to be integrated with documents seamlessly, the Template interface was developed to inherit directly from the Element interface, just like Block and Inline.

class snakemd.Template

Bases: Element

A template element in Markdown. A template can be thought of as a subdocument or collection of blocks. The entire purpose of the Template interface is to provide a superclass for a variety of abstractions over the typical markdown features. For example, Markdown has no feature for tables of contents, but a template could be created to generate one automatically for the user. In other words, templates are meant to be conviences objects for our users.


The template library is humble but growing. Feel free to share your ideas for templates on the project page or Discord. Otherwise, the existing templates can be found below.


class snakemd.TableOfContents(doc: Document, levels: range = range(2, 3))

Bases: Template

A Table of Contents is an block containing an ordered list of all the <h2> headings in the document by default. A range can be specified to customize which headings (e.g., <h3>) are included in the table of contents. This element can be placed anywhere in the document.

  • doc (Document) – a reference to the document containing this table of contents

  • levels (list[int]) – a range of integers representing the sequence of heading levels to include in the table of contents; defaults to range(2, 3)