{"id":13478508,"url":"https://github.com/didix21/mdutils","last_synced_at":"2025-12-27T09:43:07.104Z","repository":{"id":32030036,"uuid":"128527928","full_name":"didix21/mdutils","owner":"didix21","description":"Python package contains a set of basic tools that can help to create a markdown file.","archived":false,"fork":false,"pushed_at":"2024-12-29T13:18:35.000Z","size":381,"stargazers_count":212,"open_issues_count":9,"forks_count":50,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-12-29T13:22:35.302Z","etag":null,"topics":["docs","images","markdown","markdown-link","markdown-table","python","table-of-contents"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/mdutils","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/didix21.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-07T12:53:04.000Z","updated_at":"2024-12-29T13:18:39.000Z","dependencies_parsed_at":"2024-01-07T17:47:10.212Z","dependency_job_id":"4c386186-2a55-456b-b78f-c8fae193f73f","html_url":"https://github.com/didix21/mdutils","commit_stats":{"total_commits":230,"total_committers":17,"mean_commits":"13.529411764705882","dds":"0.28260869565217395","last_synced_commit":"eaa500d22bc74df0acb2571edcdc4d514689516c"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/didix21%2Fmdutils","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/didix21%2Fmdutils/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/didix21%2Fmdutils/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/didix21%2Fmdutils/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/didix21","download_url":"https://codeload.github.com/didix21/mdutils/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245802482,"owners_count":20674677,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docs","images","markdown","markdown-link","markdown-table","python","table-of-contents"],"created_at":"2024-07-31T16:01:58.008Z","updated_at":"2025-12-27T09:43:07.071Z","avatar_url":"https://github.com/didix21.png","language":"Python","readme":"# mdutils\n![Build Status](https://github.com/didix21/mdutils/actions/workflows/main.yml/badge.svg)\n[![Documentation Status](https://readthedocs.org/projects/mdutils/badge/?version=latest)](http://mdutils.readthedocs.io/en/latest/?badge=latest)\n[![codecov](https://codecov.io/gh/didix21/mdutils/branch/master/graph/badge.svg?token=0DN72Z1B6V)](https://codecov.io/gh/didix21/mdutils)\n\nTable of Contents\n=================\n- [Overview](#overview)\n- [Features](#features)\n    - [Writing and Reading Files](#writing-and-reading-files)\n    - [Markdown](#markdown)    \n- [Installation](#installation)\n- [Markdown File Example](#markdown-file-example)\n\nOverview\n=======\nThis Python package contains a set of basic tools that can help to create a markdown file while running a Python code.\nThus, if you are executing a Python code and you save the result in a text file, Why not format it? So\nusing files such as Markdown can give a great look to those results. In this way, mdutils will make things easy for\ncreating Markdown files.\n\n- Project Homepage: https://github.com/didix21/mdutils\n- Download Page: https://pypi.python.org/pypi/mdutils\n- Documentation: http://mdutils.readthedocs.io/en/latest/\n\nMIT License, (C) 2018 Dídac Coll \u003cdidaccoll_93@hotmail.com\u003e\n\nFeatures\n========\nThese are the following available features:\n\nWriting and Reading Files\n-------------------------\n- Write and Read Markdown files.\n- Append data to the end of a Markdown file.\n- Use markers to place text.\n\nMarkdown\n--------\n- Implemented method to give format to the text: **bold**, _italics_, change color...\n- Align text.\n- Add headers of levels 1 til 6 (atx style) or 1 and 2 (setext style).\n- Create tables.\n- Create a table of contents.\n- Add Links.\n- Add Lists.\n- Add Markdown Images.\n- Add Html Images.\n\n**NOTE:** some available features will depend on which CSS you are using. For example, GitHub does not allow to give color to text.\n\nInstallation\n============\n\nPip\n---\nUse pip to install mdutils:\n```bash\n$ pip install mdutils\n```\n\nPoetry\n------\nUse poetry to install mdutils:\n```bash\n$ poetry add mdutils\n```\n\nMarkdown File Example\n=====================\n\nContents\n========\n\n* [Overview](#overview)\n* [This is what you can do](#this-is-what-you-can-do)\n\t* [Create Markdown files](#create-markdown-files)\n\t* [Create Headers](#create-headers)\n\t* [Table of Contents](#table-of-contents)\n\t* [Paragraph and Text Format](#paragraph-and-text-format)\n\t* [Create a Table](#create-a-table)\n\t* [Create Links](#create-links)\n\t* [Create Lists](#create-lists)\n\t* [Add images](#add-images)\n\t* [Add HTML images](#add-html-images)\n\n# Overview\n\n\nThis is an example of a markdown file created using the 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.\n\n**IMPORTANT:** some features available in this library have no effect with the GitHub Markdown CSS. Some of them are: coloring text, centering text...\n\n\n\n# This is what you can do\n\n## Create Markdown files\n\n\nUsing the `MdUtils` class, we can define a new Markdown object by specifying its filename and optionally it's title and author. The filename is used as the path for creating the the Markdown file. From here, Markdown syntax can be created using the provided methods in the `MdUtils` class (see below for examples). Finally, `create_md_file()` is called to create the file at the specified path.\n\n\n```python\nfrom mdutils.mdutils import MdUtils\n\n\nmdFile = MdUtils(file_name='Example_Markdown',title='Markdown File Example')\n# Additional Markdown syntax...\nmdFile.create_md_file()\n```\n\n## Create Headers\n\n\nUsing the ``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.\n\n```python\nmdFile.new_header(level=1, title='Atx Header 1')\nmdFile.new_header(level=2, title='Atx Header 2')\nmdFile.new_header(level=3, title='Atx Header 3')\nmdFile.new_header(level=4, title='Atx Header 4')\nmdFile.new_header(level=5, title='Atx Header 5')\nmdFile.new_header(level=6, title='Atx Header 6')\n```\n\nTo give a header an ID (Extended Markdown syntax only), the `header_id` parameter can be used:\n```python\nmdFile.new_header(level=1, title='Header', header_id='firstheader')\n```\nThis will result in ``# Header {#firstheader}`` in the Markdown file.\n\n# Atx Header 1\n\n## Atx Header 2\n\n### Atx Header 3\n\n#### Atx Header 4\n\n##### Atx Header 5\n\n###### Atx Header 6\n\n\n```python\nmdFile.new_header(level=1, title='Setext Header 1', style='setext')\nmdFile.new_header(level=2, title='Setext Header 2', style='setext')\n```\nSetext Header 1\n===============\n\nSetext Header 2\n---------------\n\n\n\n## Table of Contents\n\n\nIf 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()``)\n\n```python\nmdFile.new_table_of_contents(table_title='Contents', depth=2)\n```\n## Paragraph and Text Format\n\n\nmdutils allows you to create paragraphs, line breaks or simply write text:\n### New Paragraph Method\n\n\n```python\nmdFile.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:\")\n```\n\nUsing ``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 makes your live easy because it can give format to the text. Lets see an example:\n\n```python\nmdFile.new_paragraph(\"This is an example of text in which has been added color, bold and italics text.\", bold_italics_code='bi', color='purple')\n```\n\n***\u003cfont color=\"purple\"\u003eThis is an example of text in which has been added color, bold and italics text.\u003c/font\u003e***\n### New Line Method\n\n\n``mdutils`` has a method which can create new line breaks. Lets see it.\n\n```python\nmdFile.new_line(\"This is an example of line break which has been created with ``new_line`` method.\")\n```  \nThis is an example of line break which has been created with ``new_line`` method.\n\nAs ``new_paragraph``, ``new_line`` allows users to give format to text using ``bold_italics_code`` and ``color`` parameters:\n\n```python\nmdFile.new_line(\"This is an inline code which contains bold and italics text and it is centered\", bold_italics_code='cib', align='center')\n```  \n***\u003ccenter\u003e``This is an inline code which contains bold and italics text and it is centered``\u003c/center\u003e***\n### Write Method\n\n\n``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``: \n\n```python\nmdFile.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 \")\nmdFile.write(\"use the following available parameters:  \\n\")\n```\n\nThe 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:  \n\n\n```python\nmdFile.write('  \\n')\nmdFile.write('bold_italics_code', bold_italics_code='bic')\nmdFile.write('  \\n')\nmdFile.write('Text color', color='green')\nmdFile.write('  \\n')\nmdFile.write('Align Text to center', align='center')\n```  \n***``bold_italics_code``***  \n\u003cfont color=\"green\"\u003eText color\u003c/font\u003e  \n\u003ccenter\u003eAlign Text to center\u003c/center\u003e  \n\n## Create a Table\n\n\nThe 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``\n\n```python\nlist_of_strings = [\"Items\", \"Descriptions\", \"Data\"]\nfor x in range(5):\n\tlist_of_strings.extend([\"Item \" + str(x), \"Description Item \" + str(x), str(x)])\nmdFile.new_line()\nmdFile.new_table(columns=3, rows=6, text=list_of_strings, text_align='center')\n```  \n\n|Items|Descriptions|Data|\n| :---: | :---: | :---: |\n|Item 0|Description Item 0|0|\n|Item 1|Description Item 1|1|\n|Item 2|Description Item 2|2|\n|Item 3|Description Item 3|3|\n|Item 4|Description Item 4|4|\n\n## Create Links\n\n### Create inline links\n\n\n``new_inline_link`` method allows you to create a link of the style: ``[mdutils](https://github.com/didix21/mdutils)``.\n\n\nMoreover, you can add bold, italics or code in the link text. Check the following examples: \n\n\n```python\nmdFile.new_line('  - Inline link: ' + mdFile.new_inline_link(link='https://github.com/didix21/mdutils', text='mdutils'))\nmdFile.new_line('  - Bold inline link: ' + mdFile.new_inline_link(link='https://github.com/didix21/mdutils', text='mdutils', bold_italics_code='b'))\nmdFile.new_line('  - Italics inline link: ' + mdFile.new_inline_link(link='https://github.com/didix21/mdutils', text='mdutils', bold_italics_code='i'))\nmdFile.new_line('  - Code inline link: ' + mdFile.new_inline_link(link='https://github.com/didix21/mdutils', text='mdutils', bold_italics_code='i'))\nmdFile.new_line('  - Bold italics code inline link: ' + mdFile.new_inline_link(link='https://github.com/didix21/mdutils', text='mdutils', bold_italics_code='cbi'))\nmdFile.new_line('  - Another inline link: ' + mdFile.new_inline_link(link='https://github.com/didix21/mdutils'))\n```\n  - Inline link: [mdutils](https://github.com/didix21/mdutils)  \n  - Bold inline link: [**mdutils**](https://github.com/didix21/mdutils)  \n  - Italics inline link: [*mdutils*](https://github.com/didix21/mdutils)  \n  - Code inline link: [``mdutils``](https://github.com/didix21/mdutils)  \n  - Bold italics code inline link: [***``mdutils``***](https://github.com/didix21/mdutils)  \n  - Another inline link: [https://github.com/didix21/mdutils](https://github.com/didix21/mdutils)\n### Create reference links\n\n\n``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\n\n```python\n[1]: https://github.com/didix21/mdutils\n```\n\nLets check some examples: \n\n\n```python\nmdFile.write('\\n  - Reference link: ' + mdFile.new_reference_link(link='https://github.com/didix21/mdutils', text='mdutils', reference_tag='1'))\nmdFile.write('\\n  - Reference link: ' + mdFile.new_reference_link(link='https://github.com/didix21/mdutils', text='another reference', reference_tag='md'))\nmdFile.write('\\n  - Bold link: ' + mdFile.new_reference_link(link='https://github.com/didix21/mdutils', text='Bold reference', reference_tag='bold', bold_italics_code='b'))\nmdFile.write('\\n  - Italics link: ' + mdFile.new_reference_link(link='https://github.com/didix21/mdutils', text='Bold reference', reference_tag='italics', bold_italics_code='i'))\n```\n  - Reference link: [mdutils][1]\n  - Reference link: [another reference][md]\n  - Bold link: [**Bold reference**][bold]\n  - Italics link: [*Italics reference*][italics]\n## Create Lists\n\n### Create unordered lists\n\n\nYou can add Markdown unordered list using ``mdFile.new_list(items, marked_with)``. Lets check an example: \n\n```\nitems = ['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']\nmdFile.new_list(items)\n```\n- Item 1\n- Item 2\n- Item 3\n- Item 4\n    - Item 4.1\n    - Item 4.2\n        - Item 4.2.1\n        - Item 4.2.2\n    - Item 4.3\n        - Item 4.3.1\n- Item 5\n\n### Create ordered lists\n\n\nYou can add ordered ones easily, too: ``mdFile.new_list(items, marked_with='1')``\n1. Item 1\n2. Item 2\n3. Item 3\n4. Item 4\n    1. Item 4.1\n    2. Item 4.2\n        1. Item 4.2.1\n        2. Item 4.2.2\n    3. Item 4.3\n        1. Item 4.3.1\n5. Item 5\n\n\nMoreover, you can add mixed list, for example: \n\n```\nitems = ['Item 1', 'Item 2', ['1. Item 2.1', '2. Item 2.2'], 'Item 3']\nmdFile.new_list(items)\n```\n- Item 1\n- Item 2\n    1. Item 2.1\n    2. Item 2.2\n- Item 3\n\n\nMaybe you want to replace the default hyphen ``-`` by a ``+`` or ``*`` then you can do: ``mdFile.new_list(items, marked_with='*')``.\n### Create checkbox lists\n\n\nFor creating checkbox lists you can use ``mdFile.new_checkbox_list(items)``.\n- [ ] Item 1\n- [ ] Item 2\n    - [ ] Item 2.1\n    - [ ] Item 2.2\n- [ ] Item 3\n\n\nIf you want to check all of them you can do: ``mdFile.new_checkbox_list(items, checked=True)``\n- [x] Item 1\n- [x] Item 2\n    - [x] Item 2.1\n    - [x] Item 2.2\n- [x] Item 3\n\n\nOr maybe you only want to check some of them, then you can add an ``x`` before each item that you want to check: \n\n```\n['Item 1', 'Item 2', ['Item 2.1', 'x Item 2.2'], 'x Item 3']\nmdFile.new_checkbox_list(items)\n```\n- [ ] Item 1\n- [ ] Item 2\n    - [ ] Item 2.1\n    - [x] Item 2.2\n- [x] Item 3\n\n## Add images\n\n### Inline Images\n\n\nYou can add inline images using ``new_inline_image`` method. Method will return: ``[image](../path/to/your/image.png)``. Check the following example: \n\n```\nmdFile.new_line(mdFile.new_inline_image(text='snow trees', path='./doc/source/images/photo-of-snow-covered-trees.jpg'))\n```  \n![snow trees](./doc/source/images/photo-of-snow-covered-trees.jpg)\n### Reference Images\n\n\nYou can add inline images using ``new_reference_image`` method. Method will return: ``[image][im]``. Check the following example: \n\n```\nmdFile.new_line(mdFile.new_reference_image(text='snow trees', path='./doc/source/images/photo-of-snow-covered-trees.jpg', reference_tag='im'))\n```  \n![snow trees][im]\n## Add HTML images\n\n### Change size to images\n\n\nWith ``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'))``\n\n\u003cimg src=\"./doc/source/images/sunset.jpg\" width=\"200\"/\u003e\n\nOr maybe only want to change height: ``mdFile.new_paragraph(Html.image(path=path, size='x300'))``\n\n\u003cimg src=\"./doc/source/images/sunset.jpg\" height=\"300\"/\u003e\n\nOr change width and height: ``mdFile.new_paragraph(Html.image(path=path, size='300x300'))``\n\n\u003cimg src=\"./doc/source/images/sunset.jpg\" width=\"300\" height=\"300\"/\u003e\n\n### Align images\n\n\nHtml.image allow to align images, too. For example you can run: ``mdFile.new_paragraph(Html.image(path=path, size='300x200', align='center'))``\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"./doc/source/images/sunset.jpg\" width=\"300\" height=\"200\"/\u003e\n\u003c/p\u003e\n\n\n[1]: https://github.com/didix21/mdutils\n[bold]: https://github.com/didix21/mdutils\n[im]: ./doc/source/images/photo-of-snow-covered-trees.jpg\n[italics]: https://github.com/didix21/mdutils\n[md]: https://github.com/didix21/mdutils\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdidix21%2Fmdutils","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdidix21%2Fmdutils","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdidix21%2Fmdutils/lists"}