The Core Markdown Generator

MarkdownGenerator overview

A MarkdownGenerator is a base class that all other valuable classes, such as MarkdownOutputGenerator and MarkdownPostGenerator inherit from.

Here’s what the MarkdownGenerator classes looks like:

class mdgen.markdown.MarkdownGenerator

This is the core class that is used to generate markdown text. You probably don’t want to use this class, unless you are extending it somehow.

new_blockquote(quote: str)

Returns a markdown blockquote.

Parameters

quote – A string containing the quote to be generated

>>> m = MarkdownGenerator()
>>> m.new_blockquote('What the heck guys???')
'> What the heck guys???'
new_bold_and_italic_text(text: str, underscore=True)

Returns the text bolded and italic.

>>> m = MarkdownGenerator()
>>> m.new_bold_and_italic_text('This is a test')
'_**This is a test**_'
new_bold_text(text: str)

Returns the text bolded.

Parameters

text – A string that will be returned as bold text

>>> m = MarkdownGenerator()
>>> m.new_bold_text('This is a test')
'**This is a test**'
new_code_block(code: str, language: str = 'python')

Returns a markdown code block. Valid languages for code formatting at: https://github.com/github/linguist/blob/master/lib/linguist/languages.yml

Parameters

  • code – A string containing the code-block to be generated

  • language – The language that the code-block will use

>>> m = MarkdownGenerator()
>>> code = """\
... import os
... print(os.uname())\
... """
>>> output = m.new_code_block(code, language="python")
>>> print(output)
```python
import os
print(os.uname())
```
new_comment(comment_text: str)

Returns the comment_text within markdown comment blocks.

>>> m = MarkdownGenerator()
>>> m.new_comment('This is a comment')
'<!-- This is a comment -->'
new_header(text: str, header_level: int = 1, linebreak=True, atx=True)

Returns a markdown header, using text and header_level, adds a linebreak to it (default behavior can be changed using linebreak=False). Smaller the header_level, larger the header.

Parameters
>>> m = MarkdownGenerator()
>>> m.new_header('This is a test header', 2)
'## This is a test header\n'
new_horizontal_rule(style: str = 'hyphens')

Returns a markdown horizontal line used to separate sections.

>>> m = MarkdownGenerator()
>>> m.new_horizontal_rule()
'---\n'
new_image(alt_text: str, image_url: str, image_title: str = '')

Returns a markdown link which can be used to link external websites, or even internal ones. If link_url is not provided, an empty link is returned.

>>> m = MarkdownGenerator()
>>> m.new_image('image one', 'http://example.org/?image=one')
'![image one](http://example.org/?image=one)'
>>> m.new_image('image two', 'http://example.org/?image=second',
... 'The 2nd image')
'![image two](http://example.org/?image=second "The 2nd image")'
new_italic_text(text: str, underscore=True)

Returns the text in italics.

Parameters

text – A string that will be returned as italic text

>>> m = MarkdownGenerator()
>>> m.new_italic_text('This is a test')
'_This is a test_'
new_linebreak()

Just returns a new line separator which can be used for linebreaks.

>>> m = MarkdownGenerator()
>>> m.new_linebreak()
'\n'

Returns a markdown link which can be used to link external websites, or even internal ones. If link_url is not provided, an empty link is returned.

>>> m = MarkdownGenerator()
>>> m.new_link('Visit this link')
'[Visit this link]()'
>>> m.new_link('Visit this link', 'http://shadyUrl.com/')
'[Visit this link](http://shadyUrl.com/)'
new_ordered_list(list_items_list: list, linebreak: bool = True)

Returns a markdown list of ordered list. list_items_list must be a list of lists (or tuples).

>>> m = MarkdownGenerator()
>>> m.new_ordered_list([('hello', 1, 3), 'hi', 'how do you do?', ('sup', 2)])
'\t3. hello\n1. hi\n1. how do you do?\n\t\t1. sup\n'
new_ordered_list_item(text: str, indent: int = 0, index: int = 1)

Returns a single ordered markdown list item. index will be the number prepended, and if not supplied, defaults to 1.

>>> m = MarkdownGenerator()
>>> m.new_ordered_list_item('hello', indent=2)
'\t\t1. hello'
new_paragraph(text: str, paragraph_size: int = 79)

Returns a markdown paragraph, each line formatted to contain paragraph_size characters each. Defaults to 79.

>>> m = MarkdownGenerator()
>>> m.new_paragraph('hello this is an epic paragraph', 12)
'hello this is an \nepic paragraph \n'
new_table(list_items_list: list)

Returns a markdown table. list_items_list must be a list of list (or tuples).

>>> m = MarkdownGenerator()
>>> table_data = [['hello', 'hi', 'how do you do?'], ['1', '2', '3', '4']]
>>> markdown_table = m.new_table(table_data)
>>> markdown_table
'|hello|hi|how do you do?|\n|-----|--|--------------|\n|1|2|3|4|\n'
new_text(text: str)

Returns the text as it is.

Parameters

text – A string that will be returned as it is

>>> m = MarkdownGenerator()
>>> m.new_text('This is a test text')
'This is a test text'
new_text_line(text: str)

Returns a new text line, and adds a linebreak to its end.

Parameters

text – A string that will be returned with a linebreak appended

>>> m = MarkdownGenerator()
>>> m.new_text_line('This is a test text line')
'This is a test text line\n'
new_unordered_list(list_items_list: list, style: str = 'asterisk', linebreak: bool = True)

Returns a markdown list of unordered list. list_items_list must be a list of lists (or tuples).

>>> m = MarkdownGenerator()
>>> m.new_unordered_list(['hello', 'hi', 'how do you do?', ('sup', 2)])
'* hello\n* hi\n* how do you do?\n\t\t* sup\n'
>>> m.new_unordered_list([('hello', 1), 'hi', 'how do you do?', ('sup', 2)])
'\t* hello\n* hi\n* how do you do?\n\t\t* sup\n'
new_unordered_list_item(text: str, indent: int = 0, style: str = 'asterisk')

Returns a single unordered markdown list item. an asterisk will be prepended by deafult, can be changed by passing style argument.

>>> m = MarkdownGenerator()
>>> m.new_unordered_list_item('hello')
'* hello'