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 Document object that is ready to be modified using any of the convenience methods available in the Document class. Both the snakemd.new_doc() function and the 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(name: Optional[str] = None) → 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()

New in version 0.9.0.

Parameters:

name (str) –

the file name of the document without the extension

Deprecated since version 0.13.0: parameter is now optional and will be removed in 1.0.0

Returns:

a new Document object

Document

Note

All of the methods described in the Document class are assumed to work without any snakemd.Element imports. In circumstances where methods may make use of Elements, such as in 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(name: Optional[str] = None)

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 block.

Parameters:

name (str) –

the file name of the document without the extension

Deprecated since version 0.13.0: parameter is now optional and will be removed in 1.0.0

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.add_block(Heading("Python is Cool!"), 2))

New in version 0.14.0: replaces add_element()

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 simple checklist to the document.

doc.add_checklist(["Okabe", "Mayuri", "Kurisu"])

New in version 0.10.0.

Parameters:

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

Returns:

the MDCheckList added to this Document

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

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

doc.add_code("x = 5")

Changed in version 0.2.0: Returns Paragraph generated by this method instead of None.

Parameters:

  • code (str) – a preformatted code string

  • lang (str) – the language for syntax highlighting

Returns:

the Paragraph added to this Document

add_element(element: Element) → Element

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

doc.add_element(Heading(Inline("Python is Cool!"), 2))

Changed in version 0.2.0: Returns Element generated by this method instead of None.

Deprecated since version 0.14.0: replaced in favor of add_block()

Parameters:

element (Element) – a markdown object (e.g., Table, Heading, etc.)

Returns:

the Element added to this Document

add_header(text: str, level: int = 1) → Header

A convenience method which adds a simple header to the document:

doc.add_header("Welcome to SnakeMD!")

Changed in version 0.2.0: returns Header generated by this method instead of None.

Deprecated since version 0.13.0: use add_heading() instead

Parameters:

  • text (str) – the text for the header

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

Returns:

the Header added to this Document

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

A convenience method which adds a simple heading to the document:

doc.add_heading("Welcome to SnakeMD!")

New in version 0.13.0: replaces add_header()

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.add_horizontal_rule()

New in version 0.2.0.

Returns:

the HorizontalRule added to this Document

add_ordered_list(items: Iterable[str]) → MDList

A convenience method which adds a simple ordered list to the document:

doc.add_ordered_list(["Goku", "Piccolo", "Vegeta"])

Changed in version 0.2.0: Returns MDList generated by this method instead of None.

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 simple paragraph of text to the document:

doc.add_paragraph("Mitochondria is the powerhouse of the cell.")

Changed in version 0.2.0: Returns Paragraph generated by this method instead of None.

Parameters:

text (str) – any arbitrary text

Returns:

the Paragraph added to this Document

add_quote(text: str) → Paragraph

A convenience method which adds a blockquote to the document:

doc.add_quote("Welcome to the Internet!")

Changed in version 0.2.0: Returns Paragraph generated by this method instead of None.

Parameters:

text (str) – the text to be quoted

Returns:

the Paragraph added to this Document

add_raw(text: str) → Raw

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

doc.add_raw("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: Optional[Iterable[Align]] = None, indent: int = 0) → Table

A convenience method which adds a simple table to the document:

doc.add_table(
    ["Place", "Name"],
    [
        ["1st", "Robert"],
        ["2nd", "Rae"]
    ],
    [snakemd.Table.Align.CENTER, snakemd.Table.Align.RIGHT],
    0
)

Changed in version 0.2.0: Returns Table generated by this method instead of None.

Changed in version 0.4.0: Added optional alignment parameter

Changed in version 0.11.0: Added optional indentation parameter

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.add_table_of_contents()

Changed in version 0.2.0: Fixed a bug where table of contents could only be rendered once.

Changed in version 0.8.0: Added optional levels parameter

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 a simple unordered list to the document.

doc.add_unordered_list(["Deku", "Bakugo", "Kirishima"])

Changed in version 0.2.0: Returns MDList generated by this method instead of None.

Parameters:

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

Returns:

the MDList added to this Document

check_for_errors() → None

A convenience method which can be used to verify the integrity of the document. Results will be printed to standard out.

New in version 0.2.0.

dump(name: str, dir: str | os.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.dump("README")

New in version 0.13.0: Replaces the output_page() method

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

output_page(dump_dir: str = '', encoding: str = 'utf-8') → None

Generates the markdown file. Assumes UTF-8 encoding.

Deprecated since version 0.13.0: Use dump() instead

Parameters:

  • dump_dir (str) – the path to where you want to dump the file

  • encoding (str) – the encoding to use

render() → str

Renders the markdown document from a list of blocks.

Deprecated since version 0.14.0: removed in favor of __str__

Returns:

the document as a markdown string

scramble() → None

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