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, and more.

Templates

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. Therefore, templates can also be verified.

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.

New in version 0.14.0.

Below are a few existing templates.

TableOfContents

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.

New in version 0.2.0.

Changed in version 0.8.0: Added optional levels parameter

Parameters:
  • 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)

verify() Verification

A Table of Contents is generated through a circular reference to the Document it contains. There is no way to instantiate this incorrectly.

New in version 0.2.0.

Returns:

a verification object from the violator