Markdown is a markup language with plain text formatting syntax. This package allows the creation of markdown-compliant strings. The following is a summary of features with usage examples.
Note: asterisk and underscores are escaped for all functions that do not format
to code (inline_code and code_block).
To install from pypi run
pip install markdown_stringsEvery standard function includes an optional keyword argument esc, set to
True by default. This parameter determines whether to escape characters in
the input text, thereby preventing them from triggering markdown formatting.
Return a header of specified level.
Keyword arguments:
- style -- Specifies the header style (default atx). The "atx" style uses hash signs, and has 6 levels. The "setext" style uses dashes or equals signs for headers of levels 1 and 2 respectively, and is limited to those two levels. The number of dashes or equals signs is either the length of the text, or 3.
Specifying a level outside of the style's range results in a ValueError.
>>> header("Main Title", 1)
'# Main Title'
>>> header("Smaller subtitle", 4)
'#### Smaller subtitle'
>>> header("Setext style", 2, style="setext")
'Setext style\\n------------'Return italics formatted text.
>>> italics("This text is italics")
'_This text is italics_'Return bold formatted text.
>>> bold("This text is bold")
'**This text is bold**'Return formatted inline code.
>>> inline_code("This text is code")
'`This text is code`'Return a code block.
If a language is specified a fenced code block is produced, otherwise the block is indented by four spaces.
Keyword arguments:
- language -- Specifies the language to fence the code in (default blank).
>>> code_block("This is a simple codeblock.")
' This is a simple codeblock.'
>>> code_block("This is a simple codeblock.\\nBut it has a linebreak!")
' This is a simple codeblock.\\n But it has a linebreak!'
>>> code_block("This block of code has a specified language.", "python")
'```python\\nThis block of code has a specified language.\\n```'
>>> code_block("So\\nmany\\nlinebreaks.", "python")
'```python\\nSo\\nmany\\nlinebreaks.\\n```'Return an inline link.
>>> link ("This is a link", "https://github.com/awesmubarak/markdown_strings")
'[This is a link](https://github.com/awesmubarak/markdown_strings)'Return an inline image.
Keyword arguments:
- title -- Specify the title of the image, as seen when hovering over it.
>>> image("This is an image", "https://avatars3.githubusercontent.com/u/24862378")
''
>>> image("This is an image", "https://avatars3.githubusercontent.com/u/24862378", "awes")
' "awes"'Return an unordered list from an list.
>>> unordered_list(["first", "second", "third", "fourth"])
'- first\\n- second\\n- third\\n- fourth'
>>> unordered_list([1, 2, 3, 4, 5])
'- 1\\n- 2\\n- 3\\n- 4\\n- 5'Return an ordered list from an list.
>>> ordered_list(["first", "second", "third", "fourth"])
'1. first\\n2. second\\n3. third\\n4. fourth'Return a blockquote.
>>> blockquote("A simple blockquote")
'> A simple blockquote'Return a horizontal rule.
Keyword arguments:
- length -- Specifies the length of the rule (default 79, minimum 3).
- style -- Character used for the rule (may be either "_" or "*").
If the length is too low, or the style is invalid, a ValueError is raised.
>>> horizontal_rule()
'_______________________________________________________________________________'
>>> horizontal_rule(length=5, style="*")
'*****'Return text with strike-through formatting.
>>> strikethrough("This is a lie")
'~This is a lie~'Return a task list.
The task_list should be a 2-dimensional iterable; the first item should be the task text and the second the boolean completion state.
>>> task_list([["Be born", True], ["Be dead", False]])
'- [X] Be born\\n- [ ] Be dead'Return a single table row.
Keyword arguments:
- pad -- The pad should be an list of the same size as the input text list. It will be used to format the row's padding.
>>> table_row(["First column", "Second", "Third"])
'| First column | Second | Third |'
>>> table_row(["First column", "Second", "Third"], [10, 10, 10])
'| First column | Second | Third |'Return a delimiter row for use in a table.
Keyword arguments:
- column_lengths -- An iterable that specifies the length of each column.
>>> table_delimiter_row(3)
'| --- | --- | --- |'
>>> table_delimiter_row(3, column_lengths=[4,5,6])
'| ---- | ----- | ------ |'Return a formatted table, generated from lists representing columns.
The function requires a 2-dimensional list, where each list is a column of the table. This will be used to generate a formatted table in string format.
>>> table([["1","2","3"], ["4","5","6"], ["7","8","9"]])
'| 1 | 4 | 7 |\\n| --- | --- | --- |\\n| 2 | 5 | 8 |\\n| 3 | 6 | 9 |'
>>> table([["Name", "Awes", "Bob"], ["User", "mub123", ""]])
'| Name | User |\\n| ---- | ------ |\\n| Awes | mub123 |\\n| Bob | |'This table, when parsed, will look like this:
| Name | User |
|---|---|
| Awes | mub123 |
| Bob |
Return a formatted table, using each list as the list. The specifics are the same as those for the table function.
>>> table_from_rows([["1","2","3"],["4","5","6"],["7","8","9"]])
'| 1 | 2 | 3 |\\n| --- | --- | --- |\\n| 4 | 5 | 6 |\\n| 7 | 8 | 9 |'Return text with formatting escaped
Markdown requires a backslash before literal underscores or asterisk, to avoid formatting to bold or italics.
Keyword arguments:
- esc -- Specifies if text should be escaped or not. This exists incase input text should not be escaped
>>> esc_format("Normal text", esc=True)
'Normal text'
>>> esc_format("Text with **bold**", esc=True) == r'Text with \\*\\*bold\\*\\*'
True
>>> esc_format("Text with _italics_", esc=True) == r'Text with \\_italics\\_'
True
>>> esc_format("Text with _**complicated** format_", esc=True) == r'Text with \\_\\*\\*complicated\\*\\* format\\_'
True