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.
The SnakeMD module is the root module of the snakemd system. It imports all classes to be used directly through snakemd, so users don’t need to know the underlying directory structure. Likewise, directory structure can be changed in future iterations of the project without affecting users.
- 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(elements: list[snakemd.elements.Element] = None)
Bases:
object
A document represents a markdown file. Documents store a collection of elements 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.- Parameters:
an optional list of elements that make up a markdown document
New in version 2.2: Included to make __repr__ more useful
- __repr__() str
Renders self as an unambiguous string for development. In this case, it displays in the style of a dataclass, where instance variables are listed with their values.
>>> doc = snakemd.new_doc() >>> repr(doc) 'Document(elements=[])'
- Returns:
the MDList object as a development string
- __str__() str
Renders the markdown document from a list of elements.
>>> doc = snakemd.new_doc() >>> doc.add_heading("First") Heading(text=[...], level=1) >>> print(doc) # First
- Returns:
the document as a markdown string
- 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)) Heading(text=[Inline(text='Python is Cool!',...)], level=2) >>> print(doc) ## Python is Cool!
- 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"]) MDList(items=[...], ordered=False, checked=False) >>> print(doc) - [ ] Okabe - [ ] Mayuri - [ ] Kurisu
- 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") Code(code='x = 5', lang='generic') >>> print(doc) ```generic x = 5 ```
- 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!") Heading(text=[Inline(text='Welcome to SnakeMD!',...)], level=1) >>> print(doc) # Welcome to SnakeMD!
- add_horizontal_rule() HorizontalRule
A convenience method which adds a horizontal rule to the document:
>>> doc = snakemd.new_doc() >>> doc.add_horizontal_rule() HorizontalRule() >>> print(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"]) MDList(items=[...], ordered=True, checked=None) >>> print(doc) 1. Goku 2. Piccolo 3. Vegeta
- 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.") Paragraph(content=[...]) >>> print(doc) Mitochondria is the powerhouse of the cell.
- 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!") Quote(content=[Raw(text='Welcome to the Internet!')]) >>> print(doc) > Welcome to the Internet!
- 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") Raw(text='X: 5\nY: 4\nZ: 3') >>> print(doc) X: 5 Y: 4 Z: 3
- add_table(header: Iterable[str], data: Iterable[Iterable[str]], align: Iterable[Align] = 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) Table(header=[...], body=[...], align=[...], indent=0) >>> print(doc) | Place | Name | | :---: | -----: | | 1st | Robert | | 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() TableOfContents(levels=range(2, 3)) >>> doc.add_heading("First Item", 2) Heading(text=[Inline(text='First Item',...)], level=2) >>> doc.add_heading("Second Item", 2) Heading(text=[Inline(text='Second Item',...)], level=2) >>> print(doc) 1. [First Item](#first-item) 2. [Second Item](#second-item) ## First Item ## 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"]) MDList(items=[...], ordered=False, checked=None) >>> print(doc) - Deku - Bakugo - Kirishima
- dump(name: str, directory: 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() HorizontalRule() >>> doc.dump("README")
- Parameters:
name (str) – the name of the markdown file to output without the file extension
directory (str | os.PathLike) –
the output directory for the markdown file; defaults to “”
Changed in version 2.2: Renamed from dir to directory to avoid built-in clashes
ext (str) – the output file extension; defaults to “md”
encoding (str) – the encoding to use; defaults to utf-8
- get_elements() list[snakemd.elements.Element]
A getter method which allows the user to retrieve the underlying document structure of elements as a list. The return value is directly aliased to the underlying representation, so any changes to this object will change the document.
The primary use of this method is to share an alias to the underlying document structure to other useful components like TableOfContents without creating circular references.
New in version 2.2: Included as a part of the TableOfContents rework
- Returns:
the list of block comprising this document