This Python package contains a set of basic tools that can help to create a markdown file while running a Python code. Thus, if you are executing a Python code and you save the result in a text file, Why not format it? So using files such as Markdown can give a great look to those results. In this way, mdutils will make things easy for creating Markdown files.
- Project Homepage: https://github.com/didix21/mdutils
- Download Page: https://pypi.python.org/pypi/mdutils
- Documentation: http://mdutils.readthedocs.io/en/latest/
MIT License, (C) 2018 Dídac Coll [email protected]
These are the following available features:
- Write and Read Markdown files.
- Append data to the end of a Markdown file.
- Use markers to place text.
- Implemented method to give format to the text: bold, italics, change color...
- Align text.
- Add headers of levels 1 til 6 (atx style) or 1 and 2 (setext style).
- Create tables.
- Create a table of contents.
- Add Links.
- Add Lists.
- Add Markdown Images.
- Add Html Images.
NOTE: some available features will depen on which CSS you are using. For example, GitHub do not allows to give color to text.
Use pip to install mdutils:
$ pip install mdutilsThis is an example of markdown file created using mdutils python package. In this example you are going to see how to create a markdown file using this library. Moreover, you're finding the available features which makes easy the creation of this type of files while you are running Python code.
IMPORTANT: some features available on this library have no effect with the GitHub Markdown CSS. Some of them are: coloring text, centering text...
create_md_file() is the last command that has to be called.
from mdutils.mdutils import MdUtils
mdFile = MdUtils(file_name='Example_Markdown',title='Markdown File Example')
mdFile.create_md_file()Using new_header method you can create headers of different levels depending on the style. There are two available styles: 'atx' and 'setext'. The first one has til 6 different header levels. Atx's levels 1 and 2 are automatically added to the table of contents unless the parameter add_table_of_contents is set to 'n'. The 'setext' style only has two levelsof headers.
mdFile.new_header(level=1, title='Atx Header 1')
mdFile.new_header(level=2, title='Atx Header 2')
mdFile.new_header(level=3, title='Atx Header 3')
mdFile.new_header(level=4, title='Atx Header 4')
mdFile.new_header(level=5, title='Atx Header 5')
mdFile.new_header(level=6, title='Atx Header 6')mdFile.new_header(level=1, title='Setext Header 1', style='setext')
mdFile.new_header(level=2, title='Setext Header 2', style='setext')If you have defined some headers of level 1 and 2, you can create a table of contents invoking the following command (Normally, the method will be called at the end of the code before calling create_md_file())
mdFile.new_table_of_contents(table_title='Contents', depth=2)mdutils allows you to create paragraph, line breaks or simply write text:
mdFile.new_paragraph("Using ``new_paragraph`` method you can very easily add a new paragraph"
" This example of paragraph has been added using this method. Moreover,"
"``new_paragraph`` method make your live easy because it can give format"
" to the text. Lets see an example:")Using new_paragraph method you can very easily add a new paragraph on your markdown file. This example of paragraph has been added using this method. Moreover, new_paragraph method make your live easy because it can give format to the text. Lets see an example:
mdFile.new_paragraph("This is an example of text in which has been added color, bold and italics text.", bold_italics_code='bi', color='purple')This is an example of text in which has been added color, bold and italics text.
mdutils has a method which can create new line breaks. Lets see it.
mdFile.new_line("This is an example of line break which has been created with ``new_line`` method.")This is an example of line break which has been created with new_line method.
As new_paragraph, new_line allows users to give format to text using bold_italics_code and color parameters:
mdFile.new_line("This is an inline code which contains bold and italics text and it is centered", bold_italics_code='cib', align='center')This is an inline code which contains bold and italics text and it is centered
write method writes text in a markdown file without jump lines '\n' and as new_paragraph and new_line, you can give format to text using the arguments bold_italics_code, color and align:
mdFile.write("The following text has been written with ``write`` method. You can use markdown directives to write:"
"**bold**, _italics_, ``inline_code``... or ")
mdFile.write("use the following available parameters: \n")The following text has been written with write method. You can use markdown directives to write: bold, italics, inline_code... or use the following available parameters:
mdFile.write(' \n')
mdFile.write('bold_italics_code', bold_italics_code='bic')
mdFile.write(' \n')
mdFile.write('Text color', color='green')
mdFile.write(' \n')
mdFile.write('Align Text to center', align='center')bold_italics_code
Text color
The library implements a method called new_table that can create tables using a list of strings. This method only needs: the number of rows and columns that your table must have. Optionally you can align the content of the table using the parameter text_align
list_of_strings = ["Items", "Descriptions", "Data"]
for x in range(5):
list_of_strings.extend(["Item " + str(x), "Description Item " + str(x), str(x)])
mdFile.new_line()
mdFile.new_table(columns=3, rows=6, text=list_of_strings, text_align='center')| Items | Descriptions | Data |
|---|---|---|
| Item 0 | Description Item 0 | 0 |
| Item 1 | Description Item 1 | 1 |
| Item 2 | Description Item 2 | 2 |
| Item 3 | Description Item 3 | 3 |
| Item 4 | Description Item 4 | 4 |
new_inline_link method allows you to create a link of the style: [mdutils](https://github.com/didix21/mdutils).
Moreover, you can add bold, italics or code in the link text. Check the following examples:
mdFile.new_line(' - Inline link: ' + mdFile.new_inline_link(link='https://github.com/didix21/mdutils', text='mdutils'))
mdFile.new_line(' - Bold inline link: ' + mdFile.new_inline_link(link='https://github.com/didix21/mdutils', text='mdutils', bold_italics_code='b')
mdFile.new_line(' - Italics inline link: ' + mdFile.new_inline_link(link='https://github.com/didix21/mdutils', text='mdutils', bold_italics_code='i')
mdFile.new_line(' - Code inline link: ' + mdFile.new_inline_link(link='https://github.com/didix21/mdutils', text='mdutils', bold_italics_code='i')
mdFile.new_line(' - Bold italics code inline link: ' + mdFile.new_inline_link(link='https://github.com/didix21/mdutils', text='mdutils', bold_italics_code='cbi')
mdFile.new_line(' - Another inline link: ' + mdFile.new_inline_link(link='https://github.com/didix21/mdutils') - Inline link: mdutils
- Bold inline link: mdutils
- Italics inline link: mdutils
- Code inline link:
mdutils - Bold italics code inline link:
mdutils - Another inline link: https://github.com/didix21/mdutils
new_reference_link method allows you to create a link of the style: [mdutils][1]. All references will be added at the end of the markdown file automatically as:
[1]: https://github.com/didix21/mdutilsLets check some examples:
mdFile.write('\n - Reference link: ' + mdFile.new_reference_link(link='https://github.com/didix21/mdutils', text='mdutils', reference_tag='1')
mdFile.write('\n - Reference link: ' + mdFile.new_reference_link(link='https://github.com/didix21/mdutils', text='another reference', reference_tag='md')
mdFile.write('\n - Bold link: ' + mdFile.new_reference_link(link='https://github.com/didix21/mdutils', text='Bold reference', reference_tag='bold', bold_italics_code='b')
mdFile.write('\n - Italics link: ' + mdFile.new_reference_link(link='https://github.com/didix21/mdutils', text='Bold reference', reference_tag='italics', bold_italics_code='i')- Reference link: mdutils
- Reference link: another reference
- Bold link: Bold reference
- Italics link: Italics reference
You can add Mark down unordered list using mdFile.new_list(items, marked_with). Lets check an example:
items = ['Item 1', 'Item 2', 'Item 3', 'Item 4', ['Item 4.1', 'Item 4.2', ['Item 4.2.1', 'Item 4.2.2'], 'Item 4.3', ['Item 4.3.1']], 'Item 5']
mdFile.new_list(items)
- Item 1
- Item 2
- Item 3
- Item 4
- Item 4.1
- Item 4.2
- Item 4.2.1
- Item 4.2.2
- Item 4.3
- Item 4.3.1
- Item 5
You can add ordered ones easily, too: mdFile.new_list(items, marked_with='1')
- Item 1
- Item 2
- Item 3
- Item 4
- Item 4.1
- Item 4.2
- Item 4.2.1
- Item 4.2.2
- Item 4.3
- Item 4.3.1
- Item 5
Moreover, you can add mixed list, for example:
items = ['Item 1', 'Item 2', ['1. Item 2.1', '2. Item 2.2'], 'Item 3']
mdFile.new_list(items)
- Item 1
- Item 2
- Item 2.1
- Item 2.2
- Item 3
Maybe you want to replace the default hyphen - by a + or * then you can do: mdFile.new_list(items, marked_with='*').
For creating checkbox lists you can use mdFile.new_checkbox_list(items).
- Item 1
- Item 2
- Item 2.1
- Item 2.2
- Item 3
If you want to check all of them you can do: mdFile.new_checkbox_list(items, checked=True)
- Item 1
- Item 2
- Item 2.1
- Item 2.2
- Item 3
Or maybe you only want to check some of them, then you can add an x before each item that you want to check:
['Item 1', 'Item 2', ['Item 2.1', 'x Item 2.2'], 'x Item 3']
mdFile.new_checkbox_list(items)
- Item 1
- Item 2
- Item 2.1
- Item 2.2
- Item 3
You can add inline images using new_inline_image method. Method will return: [image](../path/to/your/image.png). Check the following example:
mdFile.new_line(mdFile.new_inline_image(text='snow trees', path='./doc/source/images/photo-of-snow-covered-trees.jpg'))
You can add inline images using new_reference_image method. Method will return: [image][im]. Check the following example:
mdFile.new_line(mdFile.new_reference_image(text='snow trees', path='./doc/source/images/photo-of-snow-covered-trees.jpg', reference_tag='im'))
With Html.image you can change size of images in a markdown file. For example you can dothe following for changing width: mdFile.new_paragraph(Html.image(path=path, size='200'))
Or maybe only want to change height: mdFile.new_paragraph(Html.image(path=path, size='x300'))
Or change width and height: mdFile.new_paragraph(Html.image(path=path, size='300x300'))
Html.image allow to align images, too. For example you can run: mdFile.new_paragraph(Html.image(path=path, size='300x200', align='center'))