yamdog 0.6.0

Yet Another Markdown Only Generator

YAMDOG

YAMDOG is toolkit for creating Markdown text using Python. Markdown is a light and relatively simple markup language.

Table of Contents

• Quick start guide
  • The first steps
    • Installing
    • Importing
  • Using the package
    • Making elements
      • Heading
      • Example heading
      • Paragraph
      • Table
      • Compact table
      • Listing
      • Checklist
      • Link
      • Codeblock
      • Code
      • Address
      • Quote block
    • Combining elements into a document
      • Example heading
• Further reading

Quick start guide

Here's how you can start

The first steps

Installing

Install YAMDOG with pip

pip install yamdog

Importing

Import name is the same as install name, yamdog.

import yamdog

Using the package

There are two main things to building a Markdown document using YAMDOG

1. Making elements
2. Combining elements into a document

You can call str on the element directly to get the markdown source

markdown_source = str(element)

but most of the time you will compose the elements together into a document

markdown_source = str(document)

Making elements

Let's start with an empty document

document = md.Document([])

Heading

Python source

heading = md.Heading('Example heading', 4)

Markdown source

#### Example heading

Rendered result

Example heading

---

bolded text

some italiced text

striken text

==highlighted text==

==All styles combined==

bold_text = md.Text('bolded text', {md.BOLD})
italiced_text = md.Text('some italiced text', {md.ITALIC})
strikethrough_text = md.Text('striken text', {md.STRIKETHROUGH})
highlighted_text = md.Text('highlighted text', {md.HIGHLIGHT})
all_together = md.Text('All styles combined',
                               {md.BOLD, md.ITALIC,
                                md.STRIKETHROUGH, md.HIGHLIGHT})

---

Paragraph

Python source

paragraph = md.Paragraph(['Example paragraph containing ',
                          md.Text('bolded text', {md.BOLD})])

Markdown source

Example paragraph containing **bolded text**

Rendered result

Example paragraph containing bolded text

---

Table

Python source

table = md.Table([['a', 1, 'Python'],
                  ['b', 2, 'Markdown']],
                 ['First column', 'Second column', 'Third column'],
                 [md.RIGHT, md.LEFT, md.CENTER])

Markdown source

| First column | Second column | Third column |
| -----------: | :------------ | :----------: |
|            a | 1             |    Python    |
|            b | 2             |   Markdown   |

Rendered result

First column	Second column	Third column
a	1	Python
b	2	Markdown

---

You can select compact mode at the table object creation

Compact table

Python source

table = md.Table([['a', 1, 'Python'],
                  ['b', 2, 'Markdown']],
                 ['First column', 'Second column', 'Third column'],
                 [md.RIGHT, md.LEFT, md.CENTER],
                 True)

Markdown source

First column|Second column|Third column
--:|:--|:-:
a|1|Python
b|2|Markdown

Rendered result

First column	Second column	Third column
a	1	Python
b	2	Markdown

---

or later by changing the attribute compact

table.compact = True

Listing

Python source

listing = md.Listing(['Just normal text',
                      md.Text('some stylised text', {md.ITALIC}),
                      md.Checkbox('Listings can include checkboxes', False),
                      md.Checkbox('Checked and unchecked option available', True),
                      ('Sublist by using a tuple',
                        md.Listing(['first', 'second'], md.ORDERED))],
                      md.UNORDERED)

Markdown source

- Just normal text
- *some stylised text*
- [ ] Listings can include checkboxes
- [x] Checked and unchecked option available
- Sublist by using a tuple
    1. first
    2. second

Rendered result

• Just normal text
• some stylised text
• Listings can include checkboxes
• Checked and unchecked option available
• Sublist by using a tuple
  1. first
  2. second

---

Checklist

Python source

checklist = md.make_checklist([('unchecked box', False),
                               ('checked box', True),
                               ('done', True)])

Markdown source

- [ ] unchecked box
- [x] checked box
- [x] done

Rendered result

• unchecked box
• checked box
• done

---

Link

Python source

link = md.Link('https://www.markdownguide.org', 'Link to Markdown Guide')

Markdown source

[Link to Markdown Guide](https://www.markdownguide.org)

Rendered result

Link to Markdown Guide

---

Codeblock

Python source

codeblock = md.CodeBlock('import yamdog as md\n\ndoc = md.Document([])',
                         'python')

Markdown source

```python
import yamdog as md

doc = md.Document([])
```

Rendered result

import yamdog as md

doc = md.Document([])

---

Code

Python source

code = md.Code('python != markdown')

Markdown source

`python != markdown`

Rendered result

python != markdown

---

Address

Python source

address = md.Link('https://www.markdownguide.org')

Markdown source

<https://www.markdownguide.org>

Rendered result

https://www.markdownguide.org

---

Quote block

Python source

quoteblock = md.Quote('Quote block supports\nmultiple lines')

Markdown source

> Quote block supports
> multiple lines

Rendered result

Quote block supports multiple lines

---

Combining elements into a document

Initialising Document with list of elements

document = md.Document([heading, link, paragraph, listing])

adding elements into a document

document = md.Document([])
document += heading
document += link
document += paragraph
document += listing

adding elements together into a document

document = heading + link + paragraph + listing

Adding two documents together

document1 = md.Document([heading, link])
document2 = md.Document([paragraph, listing])
document = document1 + document2

Markdown source

#### Example heading

[Link to Markdown Guide](https://www.markdownguide.org)

Example paragraph containing **bolded text**

- Just normal text
- *some stylised text*
- [ ] Listings can include checkboxes
- [x] Checked and unchecked option available
- Sublist by using a tuple
    1. first
    2. second

Rendered result

Example heading

Link to Markdown Guide

Example paragraph containing bolded text

• Just normal text
• some stylised text
• Listings can include checkboxes
• Checked and unchecked option available
• Sublist by using a tuple
  1. first
  2. second

Further reading

• basic syntax guide
• extended syntax guide

Changelog

0.6.0 2024-07-16

Deprecations

• python 3.9

Features

• support for pythonn 3.13

0.5.0 2023-05-07

• Some API changes
• Added Raw, PDF, Comment

0.4.0 2023-01-23

• Much better type validation
• Some comparisons

0.3.1 2023-01-23

• Preliminary type validation
• Full test coverage