The Document API

SnakeMD is designed with different types of users in mind. The main type of user is the person who wants to design and generate markdown quickly without worrying too much about the format or styling of their documents. To help this type of user, we’ve developed a high-level API which consists of a single function, snakemd.new_doc(). This function returns a snakemd.Document object that is ready to be modified using any of the convenience methods available in the snakemd.Document class. Both the snakemd.new_doc() function and the snakemd.Document class are detailed below.

Module

The SnakeMD module contains all of the functionality for generating markdown files with Python. To get started, check out Usage for quickstart sample code.

snakemd.new_doc() → Document

Creates a new SnakeMD document. This is a convenience function that allows you to create a new markdown document without having to import the Document class. This is useful for anyone who wants to take advantage of the procedural interface of SnakeMD. For those looking for a bit more control, each element class will need to be imported as needed.

>>> doc = snakemd.new_doc()

Returns:

a new Document object

Document

Note

All of the methods described in the snakemd.Document class are assumed to work without any snakemd.Element imports. In circumstances where methods may make use of Elements, such as in snakemd.Document.add_table(), the snakemd module will be referenced directly in the sample source code.

For the average user, the document object is the only object in the library necessary to create markdown files. Document objects are automatically created from the new_doc() function of the SnakeMD module.

class snakemd.Document

Bases: object

A document represents a markdown file. Documents store a collection of blocks which are appended with new lines between to generate the markdown document. Document methods are intended to provided convenience when generating a markdown file. However, the functionality is not exhaustive. To get the full range of markdown functionality, you can take advantage of the add_block() function to provide custom markdown blocks.

add_block(block: Block) → Block

A generic function for appending blocks to the document. Use this function when you want a little more control over what the output looks like.

>>> doc = snakemd.new_doc()
>>> doc.add_block(snakemd.Heading("Python is Cool!", 2)) 
<snakemd.elements.Heading object at ...>
>>> str(doc)
'## Python is Cool!'

Parameters:

block (Block) – a markdown block (e.g., Table, Heading, etc.)

Returns:

the Block added to this Document

add_checklist(items: Iterable[str]) → MDList

A convenience method which adds a checklist to the document.

>>> doc = snakemd.new_doc()
>>> doc.add_checklist(["Okabe", "Mayuri", "Kurisu"])
<snakemd.elements.MDList object at ...>
>>> str(doc)
'- [ ] Okabe\n- [ ] Mayuri\n- [ ] Kurisu'

Parameters:

items (Iterable[str]) – a “list” of strings

Returns:

the MDList added to this Document

add_code(code: str, lang: str = 'generic') → Code

A convenience method which adds a code block to the document:

>>> doc = snakemd.new_doc()
>>> doc.add_code("x = 5")
<snakemd.elements.Code object at ...>
>>> str(doc)
'```generic\nx = 5\n```'

Parameters:

• code (str) – a preformatted code string

• lang (str) – the language for syntax highlighting

Returns:

the Code block added to this Document

add_heading(text: str, level: int = 1) → Heading

A convenience method which adds a heading to the document:

>>> doc = snakemd.new_doc()
>>> doc.add_heading("Welcome to SnakeMD!")
<snakemd.elements.Heading object at ...>
>>> str(doc)
'# Welcome to SnakeMD!'

doc.add_heading("Welcome to SnakeMD!")

Parameters:

• text (str) – the text for the heading

• level (int) – the level of the heading from 1 to 6

Returns:

the Heading added to this Document

add_horizontal_rule() → HorizontalRule

A convenience method which adds a horizontal rule to the document:

>>> doc = snakemd.new_doc()
>>> doc.add_horizontal_rule()
<snakemd.elements.HorizontalRule object at ...>
>>> str(doc)
'***'

Returns:

the HorizontalRule added to this Document

add_ordered_list(items: Iterable[str]) → MDList

A convenience method which adds an ordered list to the document:

>>> doc = snakemd.new_doc()
>>> doc.add_ordered_list(["Goku", "Piccolo", "Vegeta"])
<snakemd.elements.MDList object at ...>
>>> str(doc)
'1. Goku\n2. Piccolo\n3. Vegeta'

Parameters:

items (Iterable[str]) – a “list” of strings

Returns:

the MDList added to this Document

add_paragraph(text: str) → Paragraph

A convenience method which adds a paragraph of text to the document:

>>> doc = snakemd.new_doc()
>>> doc.add_paragraph("Mitochondria is the powerhouse of the cell.")
<snakemd.elements.Paragraph object at ...>
>>> str(doc)
'Mitochondria is the powerhouse of the cell.'

Parameters:

text (str) – any arbitrary text

Returns:

the Paragraph added to this Document

add_quote(text: str) → Quote

A convenience method which adds a blockquote to the document:

>>> doc = snakemd.new_doc()
>>> doc.add_quote("Welcome to the Internet!")
<snakemd.elements.Quote object at ...>
>>> str(doc)
'> Welcome to the Internet!'

Parameters:

text (str) – the text to be quoted

Returns:

the Quote added to this Document

add_raw(text: str) → Raw

A convenience method which adds text as-is to the document:

>>> doc = snakemd.new_doc()
>>> doc.add_raw("X: 5\nY: 4\nZ: 3")
<snakemd.elements.Raw object at ...>
>>> str(doc)
'X: 5\nY: 4\nZ: 3'

Parameters:

text (str) – some text

Returns:

the Raw block added to this Document

add_table(header: Iterable[str], data: Iterable[Iterable[str]], align: Iterable[Align] | None = None, indent: int = 0) → Table

A convenience method which adds a table to the document:

>>> doc = snakemd.new_doc()
>>> header = ["Place", "Name"]
>>> rows = [["1st", "Robert"], ["2nd", "Rae"]]
>>> align = [snakemd.Table.Align.CENTER, snakemd.Table.Align.RIGHT]
>>> doc.add_table(header, rows, align=align)
<snakemd.elements.Table object at ...>
>>> str(doc)
'| Place | Name   |\n| :---: | -----: |\n| 1st   | Robert |\n| 2nd   | Rae    |'

Parameters:

• header (Iterable[str]) – a “list” of strings

• data (Iterable[Iterable[str]]) – a “list” of “lists” of strings

• align (Iterable[Table.Align]) – a “list” of column alignment values; defaults to None

• indent (int) – indent size for the whole table

Returns:

the Table added to this Document

add_table_of_contents(levels: range = range(2, 3)) → TableOfContents

A convenience method which creates a table of contents. This function can be called where you want to add a table of contents to your document. The table itself is lazy loaded, so it always captures all of the heading blocks regardless of where the table of contents is added to the document.

>>> doc = snakemd.new_doc()
>>> doc.add_table_of_contents()
<snakemd.templates.TableOfContents object at ...>
>>> doc.add_heading("First Item", 2)
<snakemd.elements.Heading object at ...>
>>> doc.add_heading("Second Item", 2) 
<snakemd.elements.Heading object at ...>
>>> str(doc)
'1. [First Item](#first-item)\n2. [Second Item](#second-item)\n\n## First Item\n\n## Second Item'

Parameters:

levels (range) – a range of heading levels to be included in the table of contents

Returns:

the TableOfContents added to this Document

add_unordered_list(items: Iterable[str]) → MDList

A convenience method which adds an unordered list to the document.

>>> doc = snakemd.new_doc()
>>> doc.add_unordered_list(["Deku", "Bakugo", "Kirishima"])
<snakemd.elements.MDList object at ...>
>>> str(doc)
'- Deku\n- Bakugo\n- Kirishima'

Parameters:

items (Iterable[str]) – a “list” of strings

Returns:

the MDList added to this Document

dump(name: str, dir: str | PathLike = '', ext: str = 'md', encoding: str = 'utf-8') → None

Outputs the markdown document to a file. This method assumes the output directory is the current working directory. Any alternative directory provided will be made if it does not already exist. This method also assumes a file extension of md and a file encoding of utf-8, all of which are configurable through the method parameters.

>>> doc = snakemd.new_doc()
>>> doc.add_horizontal_rule()
<snakemd.elements.HorizontalRule object at ...>
>>> doc.dump("README")

Parameters:

• name (str) – the name of the markdown file to output without the file extension

• dir (str | os.PathLike) – the output directory for the markdown file; defaults to “”

• ext (str) – the output file extension; defaults to “md”

• encoding (str) – the encoding to use; defaults to utf-8

scramble() → None

A silly method which mixes all of the blocks in this document in a random order.

>>> doc = snakemd.new_doc()
>>> doc.add_horizontal_rule()
<snakemd.elements.HorizontalRule object at ...>
>>> doc.scramble()
>>> str(doc)
'***'