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. In addition, because the core element library is designed to adhere as closely to vanilla Markdown as possible, folks can also find extended markdown features here, such as checklists, alerts, 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.
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.
Alert
- class snakemd.Alert(message: str | Iterable[str | Inline | Block], kind: Kind)
Bases:
TemplateAlert is a wrapper of the Quote object to provide support for the alerts Markdown extension. While quotes can be nested in each other, alerts cannot.
Added in version 2.4: Included for user convenience
- Parameters:
- class Kind(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
Bases:
EnumKind is an enum representing the different kinds of alerts that you might place in a document.
- CAUTION = 5
As the GitHub docs state, a caution alert should “[advise] about risks or negative outcomes of certain actions.”
- IMPORTANT = 3
As the GitHub docs state, an important alert should provide “key information users need to know to achieve their goal.”
- NOTE = 1
As the GitHub docs state, a note should provide “useful information that users should know, even when skimming content.”
- TIP = 2
As the GitHub docs state, a tip should provide “helpful advice for doing things better or more easily.”
- WARNING = 4
As the GitHub docs state, a warning should provide “urgent info that needs immediate user attention to avoid problems.”
Checklist
- class snakemd.Checklist(items: Iterable[str | Inline | Block], checked: bool | Iterable[bool] = False)
Bases:
TemplateChecklist is an MDList extension to provide support for Markdown checklists, which are a Markdown extension. Previously, this feature was baked directly into MDList. However, because checklists are not a vanilla Markdown feature, they were moved here.
Added in version 2.4: Included for user convenience
- Raises:
ValueError – when the checked argument is an Iterable[bool] that does not match the number of top-level elements in the list
- Parameters:
items (Iterable[str | Inline | Block]) – a “list” of objects to be rendered as a list
checked (bool | Iterable[bool]) –
the checked state of the list
defaults to
Falsewhich renders a series of unchecked boxes (i.e.,- [ ])set to
Trueto render a series of checked boxes (i.e.,- [x])set to
Iterable[bool]to render the checked status of the top-level list elements directly
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.
Added 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