mdutil_example.py

# Python
#
# This file implements an example.
#
# This file is part of mdutils. https://github.com/didix21/mdutils
#
# MIT License: (C) 2018 Dídac Coll
#
# Usage:
# > python3 mdutil_example.py    # create example file in markdown format
# > retext Example_Markdown.md   # view file in markdown format


from mdutils.mdutils import MdUtils
from mdutils import Html

mdFile = MdUtils(file_name='Example_Markdown', title='Markdown File Example')

mdFile.new_header(level=1, title='Overview')  # style is set 'atx' format by default.

mdFile.new_paragraph("This 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.")
mdFile.new_paragraph("**IMPORTANT:** some features available on this library have no effect with the GitHub Markdown "
                     "CSS. Some of them are: coloring text, centering text...")
mdFile.new_paragraph()

# Available Features
mdFile.new_header(level=1, title="This is what you can do")

# ********************************************************************************************************************
# ***************************************************** Markdown *****************************************************
# ********************************************************************************************************************
mdFile.new_header(level=2, title="Create Markdown files")
mdFile.new_paragraph("``create_md_file()`` is the last command that has to be called.")
mdFile.insert_code("import Mdutils\n"
                   "\n"
                   "\n"
                   "mdFile = MdUtils(file_name=\'Example_Markdown\',title=\'Markdown File Example\')\n"
                   "mdFile.create_md_file()", language='python')

# ********************************************************************************************************************
# ***************************************************** Headers ******************************************************
# ********************************************************************************************************************
mdFile.new_header(level=2, title="Create Headers")
mdFile.new_paragraph("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 levels"
                     "of headers.")

mdFile.insert_code("mdFile.new_header(level=1, title='Atx Header 1')\n"
                   "mdFile.new_header(level=2, title='Atx Header 2')\n"
                   "mdFile.new_header(level=3, title='Atx Header 3')\n"
                   "mdFile.new_header(level=4, title='Atx Header 4')\n"
                   "mdFile.new_header(level=5, title='Atx Header 5')\n"
                   "mdFile.new_header(level=6, title='Atx Header 6')", language='python')

mdFile.new_header(level=1, title='Atx Header 1', add_table_of_contents='n')
mdFile.new_header(level=2, title='Atx Header 2', add_table_of_contents='n')
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.insert_code("mdFile.new_header(level=1, title='Setext Header 1', style='setext')\n"
                   "mdFile.new_header(level=2, title='Setext Header 2', style='setext')", language='python')

mdFile.new_header(level=1, title='Setext Header 1', style='setext', add_table_of_contents='n')
mdFile.new_header(level=2, title='Setext Header 2', style='setext', add_table_of_contents='n')
mdFile.new_paragraph()  # Add two jump lines

# ********************************************************************************************************************
# ******************************************** Create a table of contents ********************************************
# ********************************************************************************************************************
mdFile.new_header(level=2, title='Table of Contents')
mdFile.new_paragraph("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.insert_code("mdFile.new_table_of_contents(table_title='Contents', depth=2)", language='python')

# ********************************************************************************************************************
# ******************************************** Paragraph and Text format *********************************************
# ********************************************************************************************************************
mdFile.new_header(level=2, title="Paragraph and Text Format")
mdFile.new_paragraph("mdutils allows you to create paragraph, line breaks or simply write text:")
# *************************************************** Paragraph ******************************************************
mdFile.new_header(3, "New Paragraph Method")

mdFile.insert_code("mdFile.new_paragraph(\"Using ``new_paragraph`` method you can very easily add a new paragraph\" \n"
                   "\t\t\t\t\t \" This example of paragraph has been added using this method. Moreover,\"\n"
                   "\t\t\t\t\t \"``new_paragraph`` method make your live easy because it can give format\" \n"
                   "\t\t\t\t\t \" to the text. Lets see an example:\")", language='python')

mdFile.new_paragraph("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.insert_code("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')", language='python')

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')
# ************************************************* New Line *********************************************************
mdFile.new_header(3, "New Line Method")

mdFile.new_paragraph("``mdutils`` has a method which can create new line breaks. Lets see it.")
mdFile.insert_code("mdFile.new_line(\"This is an example of line break which has been created with ``new_line`` "
                   "method.\")", language='python')
mdFile.new_line("This is an example of line break which has been created with ``new_line`` method.")
mdFile.new_paragraph("As ``new_paragraph``, ``new_line`` allows users to give format to text using "
                     "``bold_italics_code`` and ``color`` parameters:")

mdFile.insert_code("mdFile.new_line(\"This is an inline code which contains bold and italics text and it is centered\","
                   " bold_italics_code='cib', align='center')", language='python')

mdFile.new_line("This is an inline code which contains bold and italics text and it is centered",
                bold_italics_code='cib', align='center')
# ************************************************** write **********************************************************
mdFile.new_header(3, "Write Method")
mdFile.new_paragraph("``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.insert_code("mdFile.write(\"The following text has been written with ``write`` method. You can use markdown "
                   "directives to write:\"\n"
                   "\t\t\t \"**bold**, _italics_, ``inline_code``... or \")\n"
                   "mdFile.write(\"use the following available parameters:  \\n\")", language='python')

mdFile.write("\n\nThe 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")

mdFile.insert_code("mdFile.write('  \\n')\n"
                   "mdFile.write('bold_italics_code', bold_italics_code='bic')\n"
                   "mdFile.write('  \\n')\n"
                   "mdFile.write('Text color', color='green')\n"
                   "mdFile.write('  \\n')\n"
                   "mdFile.write('Align Text to center', align='center')", language='python')

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')
mdFile.write('  \n')

# ********************************************************************************************************************
# ************************************************* Create a Table ***************************************************
# ********************************************************************************************************************
mdFile.new_header(2, "Create a Table")
mdFile.new_paragraph("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``")

mdFile.insert_code("list_of_strings = [\"Items\", \"Descriptions\", \"Data\"]\n"
                   "for x in range(5):\n"
                   "\tlist_of_strings.extend([\"Item \" + str(x), \"Description Item \" + str(x), str(x)])\n"
                   "mdFile.new_line()\n"
                   "mdFile.new_table(columns=3, rows=6, text=list_of_strings, text_align='center')", language='python')

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')

# ********************************************************************************************************************
# ************************************************** Create Link *****************************************************
# ********************************************************************************************************************

mdFile.new_header(2, "Create Links")

# *********************************************** Inline link ********************************************************

mdFile.new_header(3, "Create inline links")

link = "https://github.com/didix21/mdutils"
text = "mdutils"

mdFile.new_paragraph("``new_inline_link`` method allows you to create a link of the style: "
                     "``[mdutils](https://github.com/didix21/mdutils)``.\n")
mdFile.new_paragraph("Moreover, you can add bold, italics or code in the link text. Check the following examples: \n")

mdFile.insert_code("mdFile.new_line('  - Inline link: '"
                   " + mdFile.new_inline_link(link='{}', text='{}')) \n".format(link, text) +
                   "mdFile.new_line('  - Bold inline link: ' "
                   "+ mdFile.new_inline_link(link='{}', text='{}', bold_italics_code='b') \n".format(link, text) +
                   "mdFile.new_line('  - Italics inline link: ' "
                   "+ mdFile.new_inline_link(link='{}', text='{}', bold_italics_code='i') \n".format(link, text) +
                   "mdFile.new_line('  - Code inline link: ' "
                   "+ mdFile.new_inline_link(link='{}', text='{}', bold_italics_code='i') \n".format(link, text) +
                   "mdFile.new_line('  - Bold italics code inline link: ' "
                   "+ mdFile.new_inline_link(link='{}', text='{}', bold_italics_code='cbi') \n".format(link, text) +
                   "mdFile.new_line('  - Another inline link: ' + mdFile.new_inline_link(link='{}') \n".format(link),
                   language='python')

mdFile.new_line('  - Inline link: ' + mdFile.new_inline_link(link=link, text=text))
mdFile.new_line('  - Bold inline link: ' + mdFile.new_inline_link(link=link, text=text, bold_italics_code='b'))
mdFile.new_line('  - Italics inline link: ' + mdFile.new_inline_link(link=link, text=text, bold_italics_code='i'))
mdFile.new_line('  - Code inline link: ' + mdFile.new_inline_link(link=link, text=text, bold_italics_code='c'))
mdFile.new_line(
    '  - Bold italics code inline link: ' + mdFile.new_inline_link(link=link, text=text, bold_italics_code='cbi'))
mdFile.new_line('  - Another inline link: ' + mdFile.new_inline_link(link=link))

# *********************************************** Reference link ******************************************************
mdFile.new_header(3, "Create reference links")

mdFile.new_paragraph("``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: \n")

mdFile.insert_code("[1]: https://github.com/didix21/mdutils", language="python")
mdFile.new_paragraph("Lets check some examples: \n")

link = "https://github.com/didix21/mdutils"

mdFile.insert_code("mdFile.write('\\n  - Reference link: ' "
                   "+ mdFile.new_reference_link(link='{}', text='mdutils', reference_tag='1')\n".format(link) +
                   "mdFile.write('\\n  - Reference link: ' "
                   "+ mdFile.new_reference_link(link='{}', text='another reference', reference_tag='md')\n".format(
                       link) +
                   "mdFile.write('\\n  - Bold link: ' "
                   "+ mdFile.new_reference_link(link='{}', text='Bold reference', reference_tag='bold', bold_italics_code='b')\n".format(
                       link) +
                   "mdFile.write('\\n  - Italics link: ' "
                   "+ mdFile.new_reference_link(link='{}', text='Bold reference', reference_tag='italics', bold_italics_code='i')\n".format(
                       link),
                   language="python")

mdFile.write("\n  - Reference link: " + mdFile.new_reference_link(link=link, text='mdutils', reference_tag='1'))
mdFile.write(
    "\n  - Reference link: " + mdFile.new_reference_link(link=link, text='another reference', reference_tag='md'))
mdFile.write("\n  - Bold link: " + mdFile.new_reference_link(link=link, text='Bold reference', reference_tag='bold',
                                                             bold_italics_code='b'))
mdFile.write(
    "\n  - Italics link: " + mdFile.new_reference_link(link=link, text='Italics reference', reference_tag='italics',
                                                       bold_italics_code='i'))

# ********************************************************************************************************************
# ************************************************** Create Lists *****************************************************
# ********************************************************************************************************************
mdFile.new_header(2, "Create Lists")
# *********************************************** Unordered Lists ******************************************************
mdFile.new_header(3, "Create unordered lists")
mdFile.new_paragraph(
    "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.insert_code(f'items = {items}\n'
                   f'mdFile.new_list(items)\n')
mdFile.new_list(items=items)

# *********************************************** Ordered Lists ******************************************************
mdFile.new_header(3, "Create ordered lists")
mdFile.new_paragraph("You can add ordered ones easily, too: ``mdFile.new_list(items, marked_with='1')``")
mdFile.new_list(items=items, marked_with='1')

mdFile.new_paragraph("Moreover, you can add mixed list, for example: ")
items = ["Item 1", "Item 2", ["1. Item 2.1", "2. Item 2.2"], "Item 3"]
mdFile.insert_code(f'items = {items}\n'
                   f'mdFile.new_list(items)\n')
mdFile.new_list(items)
mdFile.new_paragraph("Maybe you want to replace the default hyphen ``-`` by a ``+`` or ``*`` then you can do: "
                     "``mdFile.new_list(items, marked_with='*')``.")

# ********************************************************************************************************************
# ************************************************** Add Images ******************************************************
# ********************************************************************************************************************

mdFile.new_header(2, "Add images")

# *********************************************** Inline Image *******************************************************

image_text = "snow trees"
path = "./doc/source/images/photo-of-snow-covered-trees.jpg"

mdFile.new_header(3, "Inline Images")

mdFile.new_paragraph("You can add inline images using ``new_inline_image`` method. Method will return: "
                     "``[image](../path/to/your/image.png)``. Check the following example: ")
mdFile.insert_code("mdFile.new_line(mdFile.new_inline_image(text='{}', path='{}'))".format(image_text, path))
mdFile.new_line(mdFile.new_inline_image(text=image_text, path=path))

# *********************************************** Reference Image *****************************************************
mdFile.new_header(3, "Reference Images")
mdFile.new_paragraph("You can add inline images using ``new_reference_image`` method. Method will return: "
                     "``[image][im]``. Check the following example: ")
mdFile.insert_code(
    "mdFile.new_line(mdFile.new_reference_image(text='{}', path='{}', reference_tag='im'))".format(image_text, path))
mdFile.new_line(mdFile.new_reference_image(text=image_text, path=path, reference_tag='im'))

# ************************************************* Html Image *******************************************************

mdFile.new_header(2, "Add HTML images")

# *********************************************** Size Image *******************************************************

mdFile.new_header(3, "Change size to images")
path = "./doc/source/images/sunset.jpg"

mdFile.new_paragraph("With ``Html.image`` you can change size of images in a markdown file. For example you can do"
                     "the following for changing width: ``mdFile.new_paragraph(Html.image(path=path, size='200'))``")

mdFile.new_paragraph(Html.image(path=path, size='200'))

mdFile.new_paragraph(
    "Or maybe only want to change height: ``mdFile.new_paragraph(Html.image(path=path, size='x300'))``")
mdFile.new_paragraph(Html.image(path=path, size='x300'))

mdFile.new_paragraph("Or change width and height: ``mdFile.new_paragraph(Html.image(path=path, size='300x300'))``")
mdFile.new_paragraph(Html.image(path=path, size='300x300'))
mdFile.write('\n')

# *********************************************** Align Image *******************************************************

mdFile.new_header(3, "Align images")
mdFile.new_paragraph("Html.image allow to align images, too. For example you can run: "
                     "``mdFile.new_paragraph(Html.image(path=path, size='300x200', align='center'))``")

mdFile.new_paragraph(Html.image(path=path, size='300x200', align='center'))

# Create a table of contents
mdFile.new_table_of_contents(table_title='Contents', depth=2)
mdFile.create_md_file()