YAMDOG is toolkit for creating Markdown text using Python. Markdown is a light and relatively simple markup language.
Here's how you can start
Install YAMDOG with pip
pip install yamdog
Import name is the same as install name, yamdog.
import yamdogThere are two main things to building a Markdown document using YAMDOG
- Making elements
- 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)Let's start with an empty document
document = md.Document([])Python source
heading = md.Heading('Example heading', 4)Markdown source
#### Example headingRendered result
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})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
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
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|MarkdownRendered result
| First column | Second column | Third column |
|---|---|---|
| a | 1 | Python |
| b | 2 | Markdown |
or later by changing the attribute compact
table.compact = TruePython 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. secondRendered result
- Just normal text
- some stylised text
- Listings can include checkboxes
- Checked and unchecked option available
- Sublist by using a tuple
- first
- second
Python source
checklist = md.make_checklist([('unchecked box', False),
('checked box', True),
('done', True)])Markdown source
- [ ] unchecked box
- [x] checked box
- [x] doneRendered result
- unchecked box
- checked box
- done
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
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([])Python source
code = md.Code('python != markdown')Markdown source
`python != markdown`Rendered result
python != markdown
Python source
address = md.Link('https://www.markdownguide.org')Markdown source
<https://www.markdownguide.org>Rendered result
Python source
quoteblock = md.Quote('Quote block supports\nmultiple lines')Markdown source
> Quote block supports
> multiple linesRendered result
Quote block supports multiple lines
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 += listingadding elements together into a document
document = heading + link + paragraph + listingAdding two documents together
document1 = md.Document([heading, link])
document2 = md.Document([paragraph, listing])
document = document1 + document2Markdown 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. secondRendered result
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
- first
- second
- python 3.9
- support for pythonn 3.13
- Some API changes
- Added Raw, PDF, Comment
- Much better type validation
- Some comparisons
- Preliminary type validation
- Full test coverage