mkmd#

Installation#

pip install mkmd

Quickstart#

import mkmd

with mkmd.Markdown("document.md") as md:
     md.add_heading("Welcome")
     md.add_paragraph("Thank you for using mkmd!")

API#

mkmd#

class mkmd.Markdown(path=None, width=None)#

Class that holds all Markdown content. All add_* methods return the object itself so these methods can be chained. For example:

md = Markdown()
(md
    .add_heading("Hello")
    .add_paragraph("Lorem ipsum dolor sit amet.")
    .add_horizontal_rule()
    .add_codeblock("import mkmd", language = "python")
    .save("lorem-ipsum.md")
)
lines#

Lines of the Markdown document.

Parameters

  • path (Optional[str | PathLike[str] | TextIO]) – This should only be set when using as a context manager. Otherwise use the save() method and provide the path there.

  • width (Optional[int]) – The maximum amount of characters a line can contain.

classmethod from_string(text, *args, **kwargs)#

Loads document from a string.

Parameters

  • text (str) – Markdown document as a string.

  • args (Any) – Positional arguments passed to constructor.

  • kwargs (Any) – Keyword arguments passed to constructor.

Return type

mkmd.Markdown

classmethod from_file(path, *args, **kwargs)#

Loads document from a file.

Parameters

  • path (str | os.PathLike[str] | TextIO) – Markdown document as path or file object.

  • args (Any) – Positional arguments passed to constructor.

  • kwargs (Any) – Keyword arguments passed to constructor.

Return type

mkmd.Markdown

save(path)#

Writes the Markdown document to a file. Alternatively a context manager may be used.

Parameters

path (str | os.PathLike[str] | TextIO) – A file-like object or path to save contents to.

Return type

None

Example

# these are all equivalent:

with open("document.md", "w") as f:
    md.save(f)

md.save("document.md")

md.save(Path("document.md"))
add_lines(*lines)#

Adds lines.

Attention

This method should only used by subclasses. Usually the wrapper method add_paragraph() does the job.

Parameters

lines (Optional[str]) – Lines to add. None will be skipped.

Return type

mkmd.Markdown

add_heading(text, level=1, alternate=True)#
Parameters

  • text (str) – The content of the heading.

  • level (int) – A heading level between 1 and 7 inclusive.

  • alternate (bool) – Uses hyphens and equal signs respectively instead of number signs for heading level 1 and 2.

Return type

mkmd.Markdown

add_paragraph(*lines, wrapped=False)#

Adds a paragraph.

Parameters

  • lines (Optional[str]) – Lines to add. None will be skipped.

  • wrapped (bool) – Removes indention of each line.

Return type

mkmd.Markdown

add_codeblock(text, language=None, wrapped=True)#

Adds a code block.

Parameters

  • text (str) – The content of the code block.

  • language (Optional[str]) – The programming language of the content.

  • wrapped (bool) – Interprets text in a docstring-like syntax. This calls inspect.cleandoc on text.

Return type

mkmd.Markdown

add_horizontal_rule(style='-', width=None)#

Adds a horizontal rule

Parameters

  • style (str) – What characters to use for the horizontal rule. One of *, - or _.

  • width (Optional[int]) – The width of the horizontal rule. Defaults to width if provided otherwise 20.

Return type

mkmd.Markdown

add_reference(label, url, title=None)#

Adds a reference.

Parameters

  • label (str) – The unique lable of the reference.

  • url (str) – The url to link to.

  • title (Optional[str]) – An optional title to use.

Return type

mkmd.Markdown

add_image(alt_text, path_or_url, title=None, link=None)#

Adds an image.

Parameters

  • alt_text (str) – The alternative text to display.

  • path_or_url (str | pathlib.Path) –

    Path or url of image to display.

    Attention

    Paths are relative from the markdown document, not from the python file.

  • title (Optional[str]) – An optional title to use.

  • link (Optional[str]) – Optional url to link to.

Return type

mkmd.Markdown

add_unordered_list(*items, style='-')#

Adds an unordered list.

Parameters

  • items (str) – All list items.

  • style (str) – What characters to use list. One of -, * or +.

Return type

mkmd.Markdown

add_ordered_list(*items)#

Adds an ordered list.

Parameters

items (str) – All list items.

Return type

mkmd.Markdown

mkmd.utils#

mkmd.utils.italic(text)#

Makes text italic.

Parameters

text (str) – The text to make italic.

Return type

str

mkmd.utils.bold(text)#

Makes text bold.

Parameters

text (str) – The text to make bold.

Return type

str

mkmd.utils.bold_and_italic(text)#

Makes text bold and italic.

Parameters

text (str) – The text to make bold and italic.

Return type

str

Adds a link.

Parameters

  • url (str) – The url to redirect to.

  • title (Optional[str]) – Text to display instead of the url.

Return type

str

mkmd.utils.email(address)#

Adds an email.

Parameters

address (str) – Email address to add.

Return type

str

mkmd.utils.refer(text, label)#

Refers to a reference added by mkmd.Markdown.add_reference().

Parameters

  • text (str) – Text to display.

  • label (str) – The label of the reference.

Return type

str