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:
ElementA 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 convience objects for our users.
One cool feature of templates is that they are lazy loaded. Unlike traditional elements, this means templates aren’t fully loaded until they are about to be rendered. The benefit is that we can place templates in our documents as placeholders without much configuration. Then, right before the document is rendered, the template will be injected with a reference to the contents of the document. As a result, templates are able to take advantage of the final contents of the document, such as being able to generate a word count from the words in the document or generate a table of contents from the headings in the document.
Note that the user does not have to worry about lazy loading at all. The document will take care of the dependency injection. If, however, the user needs to render a template outside the context of a document, they must call the load function manually.
- load(elements: list[snakemd.elements.Element]) None
Loads the template with a list of elements, presumably from an existing document.
- Parameters:
elements – a list of document elements
Templates
The template library is humble but growing. Feel free to share your ideas for templates on the project page or Discord. If you’d like to help create templates, the interface is available for subclassing. Your templates can either be included directly in snakemd, or you’re free to create your own template library by importing snakemd. In the former case, the template should make use of the Python standard library only and not make use of any external dependencies. In the latter case, that restriction does not apply. With that said, the existing templates can be found below.
CSVTable
- class snakemd.CSVTable(path: PathLike, encoding: str = 'utf-8')
Bases:
TemplateA CSV Table is a wrapper for the Table Block, which provides a seamless way to load CSV data into Markdown. Because Markdown tables are required to have headers, the first row of the CSV is assumed to be a header. Future iterations of this template may allow users to select the exact row for their header. Future iterations may also allow for different CSV dialects like Excel.
New in version 2.2: Included to showcase the possibilities of templates
- Parameters:
path (os.Pathlike) – the path to a CSV file
encoding (str) – the encoding of the CSV file; defaults to utf-8
TableOfContents
- class snakemd.TableOfContents(levels: range = range(2, 3))
Bases:
TemplateA Table of Contents is an element 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.
Changed in version 2.2: Removed the doc parameter