API overview

For the basic usage of Python-Markups, one should import some markup class from markups, create an instance of that class, and use the convert() method:

>>> import markups
>>> markup = markups.ReStructuredTextMarkup()
>>> markup.convert('*reStructuredText* test').get_document_body()
'<div class="document">\n<p><em>reStructuredText</em> test</p>\n</div>\n'

For advanced usage (like dynamically choosing the markup class), one may use one of the functions documented below.

Getting lists of available markups

markups.get_all_markups() → list[type[AbstractMarkup]]
Returns:

list of all markups (both standard and custom ones)

markups.get_available_markups() → list[type[AbstractMarkup]]
Returns:

list of all available markups (markups whose available() method returns True)

Getting a specific markup

markups.get_markup_for_file_name(filename: str, return_class: Literal[False] = False) → AbstractMarkup | None
markups.get_markup_for_file_name(filename: str, return_class: Literal[True]) → type[AbstractMarkup] | None
Parameters:

  • filename – name of the file

  • return_class – if true, this function will return a class rather than an instance

Returns:

a markup with file_extensions attribute containing extension of filename, if found, otherwise None

>>> import markups
>>> markup = markups.get_markup_for_file_name('foo.mkd')
>>> markup.convert('**Test**').get_document_body()
'<p><strong>Test</strong></p>\n'
>>> markups.get_markup_for_file_name('bar.rst', return_class=True)
<class 'markups.restructuredtext.ReStructuredTextMarkup'>
markups.find_markup_class_by_name(name: str) → type[AbstractMarkup] | None
Returns:

a markup with name attribute matching name, if found, otherwise None

>>> import markups
>>> markups.find_markup_class_by_name('textile')
<class 'markups.textile.TextileMarkup'>

Configuration directory

Some markups can provide configuration files that the user may use to change the behavior.

These files are stored in a single configuration directory.

If XDG_CONFIG_HOME is defined, then the configuration directory is it. Otherwise, it is .config subdirectory in the user’s home directory.