`t-python-markdown`¶

t-python-markdown is a simple to use markdown generator for Python available through PyPI.

Installation¶

Install t-python-markdown using pip as follows:

pip install t-python-markdown

Usage¶

Creating a Document¶

To create a markdown document, simply create a root object and then add other "child" objects to it. Most objects allow further child objects to be added. For example, adding a string to a Paragraph, simply extends that paragraph.

To add a child to a parent use the >> directive where the left object is the parent and the right object the child. This is declaring that the right object is the parent of the left object.

For example, adding a paragraph to a document would look as follows:

Kroki

All child objects can only have one parent. As such, you cannot, for example, create a CodeBlock and then add it to a second object or a second time to the first object. This means that the following code will fail at line 4:

Code

doc = Document()
cb = CodeBlock("ls\nfind / -name README.md")
doc >> cb
doc >> cb

Writing Output to a File¶

All objects support write({file}) and can be used to write an objects markdown, including its children, to a file.

Code

doc = Document()
doc.write("example.md")

Markdown as a String¶

All objects support output as a property to extract the markdown as a string. Alternatively, use the str() function to return a string version of the object.

Code: outputCode: str()

doc = Document()
doc >> Header("A Header")
md = doc.output

doc = Document()
doc >> Header("A Header")
md = str(doc)

Adding Inline HTML¶

Inline HTML

Markdown is not a replacement for HTML, or even close to it. Its syntax is very small, corresponding only to a very small subset of HTML tags. The idea is not to create a syntax that makes it easier to insert HTML tags. In my opinion, HTML tags are already easy to insert. The idea for Markdown is to make it easy to read, write, and edit prose. HTML is a publishing format; Markdown is a writing format. Thus, Markdown’s formatting syntax only addresses issues that can be conveyed in plain text.

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

It is possible to simply add text directly to any object to supplement any output requirements you may have. For example, use the following to add a div:

CodeOutput

doc = Document()
t = Table(["Id", "Description"], alignment=[":--"])
t >> ["1", "One"]
t >> ["2", "Two"]
doc >> '<div class="my-class">'
doc >> t
doc >> '</div>'

<div class="my-class">
⤶
| **Id** | **Description** |
| :-- | :-- |
| 1 | One |
| 2 | Two |
⤶
</div>

Ensure that you include any required carriage returns required for block-level HTML elements. See Inline HTML for details

Markdown Objects¶

Blank lines included in the output are represented by the symbol ⤶

Document¶

Document takes one optional argument, front matter, a dictionary, and is output as YAML.

CodeOutputParameters

front_matter = {"title": "A Title", "hide": ["navigation"]}
doc = Document(front_matter)
doc.write("example.md")

---
title: A Title
hide:
- navigation
...

front_matter= Front-matter (optional)

Header takes two arguments, a title and a level. The level relates to the header tags <h1> - <h6>.

CodeOutputParameters

header = Header("Header Title", 2)
doc >> header

## Header Title

title= Header title
level= Header level (default=1)

Paragraph¶

Paragraph takes a list of sentences. A sentence could be a simple string or a Sentence (see below).

CodeOutputParameters

p = Paragraph(["A sentence.", Sentence(["The quick", "brown fox"])])
doc >> p

⤶
A sentence. The quick brown fox.
⤶

o= Markdown object or objects (optional)

Sentence¶

Sentence takes three arguments, an array of strings or other markdown objects, a separator (defaults to space) and an end character (defaults to a full stop).

CodeOutputParameters

s = Sentence(["The quick", "brown fox"], end="!")
doc >> s

The quick brown fox!

o= Markdown object or objects (optional)
separator= String to use between each sentence (default=" ")
end= String to append to the sentence (default=".")

Horizontal Rule¶

HorizontalRule takes no arguments and produces a --- in the output.

CodeOutputParameters

hr = HorizontalRule()
doc >> hr

⤶
---
⤶

None

Link¶

Link takes three arguments, a title, a url and an optional alternate title.

CodeOutputParameters

l = Link("Title", "http://localhost/")
doc >> l

[Title](http://localhost/ "Title")

title= Link title
url= Link URL
alt_title= Alternate title. If not provided, will set to "title" (optional)

Image¶

Image takes two arguments, a title and a url (path to image).

CodeOutputParameters

i = Image("Picture", "/images/nice_piccie.png")
doc >> i

![Picture](/images/nice_piccie.png "Picture")

title= Link title
url= Link URL

Bold¶

Bold takes one argument, the text to be bolded.

CodeOutputParameters

bt = Bold("Bold Text")
doc >> bt

**Bold Text**

o= Text or markdown object

Italic¶

Italic takes one argument, the text to be italicised.

CodeOutputParameters

it = Italic("Italic Text")
doc >> it

*Italic Text*

o= Text or markdown object

Bold/Italic¶

BoldItalic takes one argument, the text to be bolded and italicised.

CodeOutputParameters

bit = BoldItalic("Bold/Italic Text")
doc >> bit

***Bold/Italic Text***

o= Text or markdown object

Strikethrough¶

Strikethrough takes one argument, the text to strikethrough.

CodeOutputParameters

st = Strikethrough("Strikethrough Text")
doc >> st

~~Strikethrough Text~~

o= Text or markdown object

Code¶

Code takes one argument, the text to be output as code.

CodeOutputParameters

c = Code("find / -name README.md")
doc >> c

`find / -name README.md`

o= Text or markdown object

Code Block¶

CodeBlock takes one argument, the text to output as code in a block.

CodeOutputParameters

cb = CodeBlock("ls\nfind / -name README.md")
doc >> cb

```
ls
find / -name README.md
```
⤶

o= Text or markdown object

Unordered List¶

UnorderedList takes one optional argument, a list of items. Further items can be added to the resultant object.

CodeOutputParameters

ul = UnorderedList()
ul >> "List entry 1"
ul >> "List entry 2"
doc >> ul

or

ul = UnorderedList(["List entry 1", "List entry 2"])
doc >> ul

⤶
- List entry 1
- List entry 2
⤶

o= List of text or markdown objects

Ordered List¶

OrderedList takes one optional argument, a list of items. Further items can be added to the resultant object.

CodeOutputParameters

ol = OrderedList()
ol >> "List entry 1"
ol >> "List entry 2"
doc >> ol

or

ol = OrderedList(["List entry 1", "List entry 2"])
doc >> ol

⤶
1. List entry 1
1. List entry 2
⤶

o= List of text or markdown objects

Table¶

Table takes two arguments, a list of column headers and a list of column alignments. The resultant object is then used to add rows, each row being a list of columns. The number of column alignments is adjusted to match the number of columns. If the number of alignments is too small, the last alignment is repeated to fill the missing ones. If no alignment is provided, it defaults to centred (":-:").

CodeOutputParameters

t = Table(["Id", "Description"], alignment=[":--"])
t >> ["1", "One"]
t >> ["2", "Two"]
doc >> t

| **Id** | **Description** |
| :-- | :-- |
| 1 | One |
| 2 | Two |
⤶

heading= Array of column headers
alignment= Array of column alignments

Embedding Tables and Lists¶

Embedding requires the Markdown package to be installed prior to use.

Since 1.3.0 it is possible to easily embed tables in both lists and other tables as follows:

t = Table(["Id", "Description"], alignment=["--:"])
t >> ["1", "One"]
t >> ["2", UnorderedList(["Item a", "Item b"])]
ul = UnorderedList(["Item 1", t, "Item 3"])
doc >> ul

resulting in:

Item 1
Id Description
1 One
2
Item a
Item b
Item 3

The following is a slightly more complex example showing multiple embedded lists and tables:

from t_python_markdown import Document, Table, UnorderedList

def add_row(parent, count=1):
  t = Table(["Key", "Value"])
  t >> ["Hello", "World"]
  parent >> [f"Table {count}", UnorderedList([t])]
  if count < 4:
    add_row(t, count + 1)

doc = Document()
t = Table(["Key", "Value"])
doc >> t
add_row(t)

which results in:

Key

Value

Table 1

Key Value
Hello World
Table 2
Key Value
Hello World
Table 3
Key Value
Hello World
Table 4
Key Value
Hello World

Id	Description
1	One
2	Item a Item b

t-python-markdown¶

Installation¶

Usage¶

Creating a Document¶

Writing Output to a File¶

Markdown as a String¶

Adding Inline HTML¶

Markdown Objects¶

Document¶

Header¶

Paragraph¶

Sentence¶

Horizontal Rule¶

Link¶

Image¶

Bold¶

Italic¶

Bold/Italic¶

Strikethrough¶

Code¶

Code Block¶

Unordered List¶

Ordered List¶

Table¶

Embedding Tables and Lists¶

`t-python-markdown`¶