Using Verto¶
Using Verto to convert Markdown is a process of:
- Importing the installed Verto package.
- Creating a Verto converter.
- Passing Markdown text through the Verto
convert
method and saving the result object. - Accessing data from the result object.
Step 1: Importing Verto¶
If Verto has been installed correctly, importing the package can be completed by:
import verto
Step 2: Creating Verto converter¶
Once the module is imported, you can create a Verto converter creating an Verto object:
converter = verto.Verto()
Verto()
has optional parameters to customise the converter. These are:
processors
- A set of processor names given as strings for the converter to use. If this parameter is not given, the default processors are used. Ifprocessors
is provided, all processors not listed are skipped.For example: Creating a Verto converter that only deletes comment tags would be done by the following command:
converter = verto.Verto(processors={"comment"})
html_templates
- A dictionary of HTML templates to override existing HTML templates for processors. The dictionary contains processor names given as a string as keys mapping HTML strings as values.The documentation page for each processor specificies how to create custom HTML for that processor.
For example: Creating a Verto converter that uses
<img src={{ source }}>
as custom HTML forimage
tags would be done by the following command:converter = verto.Verto(html_templates={'image': '<img src={{ source }}>'})
extensions
- A list of extra Markdown extensions to run in the converter. Details on how to use this parameter can be found on the Extensions page.settings
- A dictionary of settings to override default Verto settings. The following settings are available:add_default_interactive_thumbnails_to_required_files
- Boolean stating whether default interactive thumbnail filepaths should be added to the required files set of images. Default isTrue
.add_custom_interactive_thumbnails_to_required_files
- Boolean stating whether custom interactive thumbnail filepaths provided as tag arguments should be added to the required files set of images. External images are never added. Default isTrue
.processor_argument_overrides
- A dictionary to modify the default argument rules for each tag. The default rules can found by reading the documentation for each tag.For example: By default, the
image-inline
tag requires alt text to be given, to change this, the following custom argument rules would be used:{ "image-inline": { "alt": False } }
Warning
Some tags have multiple processors behind them (for example, the
image-inline
,image-container
andimage-tag
processors are all used for images). This means that if you would like to change the default rules of one or more of their arguments, this will need to be done for each of the processors individually. For example, to set thealt
argument asFalse
for all images, the custom argument rules would look as follows:{ "image-inline": { "alt": False }, "image-tag": { "alt": False }, "image-container": { "alt": False } }
Step 3: Convert Markdown with converter¶
To convert Markdown to HTML with a Verto converter, we call the convert()
method. The method returns a VertoResult
object.
text = """
This **is** a line of Markdown.
{comment This is a comment using a Verto tag}
This is a *different* line of Markdown.
"""
result = converter.convert(text)
Step 4: Accessing VertoResult data¶
The VertoResult
object contains several attributes which can be accessed using the dot notation. Continuing from our previous example, the following command would print the converted HTML.
print(result.html_string)
The following attributes are available:
html_string
- A resulting string of HTML after conversion by Verto.title
- The text of the first heading saved by thesave-title
processor.required_files
- A dictionary of files encountered in a Verto conversion. The dictionary has a string for the file type as the key (for example:image
) and a set of all file paths encountered as the value (for example:{'image/face.png', 'image/logo.png`}
).heading_tree
- A tuple of namedtuples which describes the tree of headings, as generated by our heading processor. Each namedtuple contains atitle
(string),title_slug
(string),level
(integer) andchildren
(tuple of nodes).For example the heading root after a conversion of a file:
( HeadingNode(title='This is an H1', title_slug='this-is-an-h1', level=1, children=( HeadingNode(title='H2 Title', title_slug='h2-title', level=2, children=()) )), HeadingNode(title='This is an H1', title_slug='this-is-an-h11', level=1, children=()), )
required-glossary-terms
- A dictionary of term slugs to a list of tuples containing reference text and link IDs.Here is an example of the
required-glossary-terms
after a conversion of a file:required-glossary-terms = { "algorithm": [("Binary Search", "glossary-algorithm"), ("Quick Sort", "glossary-algorithm-2"), ("Merge Sort", "glossary-algorithm-3")], "alphabet": [("Formal Languages", "glossary-alphabet")], "brooks-law": [] }
(Optional) Step 5: Clearing Saved Data¶
Lastly there is some data that is saved between conversions such as required_files
and unique ids used in the glossary
and for headings
. This can be cleared by using the following method:
converter.clear_saved_data()
Configuring Verto converter after creation¶
The following functions allow you to change the processors or HTML templates used in conversion by the Verto converter after its creation.
Changing processors¶
-
Verto.
update_processors
(processors) Update the processors used for conversion with the given set. The updated set will be used for converting from this point onwards. If parameter is empty, default processors will be used.
Parameters: processors – A set of processor names given as strings for which their processors are enabled. If given, all other processors are skipped.
-
static
Verto.
processor_defaults
(processors) Returns a copy of the default processor set.
Returns: A set of default processor names as strings. This function is useful if you want to make minor changes to the default used processors. For example: You wish to still use all default processors but skip video tags:
processors = Verto.processor_defaults() processors.remove('video') converter = Verto(processors=processors)
Or with an existing Verto instance
converter
:processors = Verto.processor_defaults() processors.remove('video') converter.update_processors(processors)
Changing HTML templates¶
-
Verto.
update_templates
(html_templates) Update the template dictionary with the given dictionary of templates, while leaving all other HTML templates (including any custom set templates) untouched. The updated dictionary will be used for converting from this point onwards.
Parameters: html_templates – A dictionary of HTML templates to override existing HTML templates for processors. Dictionary contains processor names given as a string as keys mapping HTML strings as values. eg: {‘image’: ‘<img src={{ source }}>’}
-
Verto.
clear_templates
() Set the template dictionary to it’s original values.
Full list of package methods¶
-
class
verto.
Verto
¶ A converter object for converting markdown with complex elements to HTML.
-
__init__
(processors=frozenset({'boxed-text', 'blockquote', 'iframe', 'save-title', 'conditional', 'interactive-container', 'external-link', 'comment', 'panel', 'style', 'image-tag', 'button-link', 'heading', 'scratch', 'scratch-inline', 'image-inline', 'glossary-link', 'video', 'interactive-tag', 'relative-link', 'image-container', 'table-of-contents'}), html_templates={}, extensions=[], settings={})¶ Creates a Verto object.
Parameters: - processors – A set of processor names given as strings for which their processors are enabled. If given, all other processors are skipped.
- html_templates – A dictionary of HTML templates to override existing HTML templates for processors. Dictionary contains processor names given as a string as keys mapping HTML strings as values. eg: {‘image’: ‘<img src={{ source }}>’}
- extensions – A list of extra extensions to run on the markdown package.
- settings – A dictionary of settings to override default settings.
-
clear_saved_data
()¶ Clears data that is saved between documents. This should be called between conversions on unrelated documents.
-
clear_templates
()¶ Set the template dictionary to it’s original values.
-
convert
(text)¶ Return a VertoResult object after converting the given markdown string.
Parameters: text – A string of Markdown text to be converted. Returns: A VertoResult object.
-
static
processor_defaults
()¶ Returns a copy of the default processor set.
Returns: A set of default processor names as strings.
-
update_processors
(processors=frozenset({'boxed-text', 'blockquote', 'iframe', 'save-title', 'conditional', 'interactive-container', 'external-link', 'comment', 'panel', 'style', 'image-tag', 'button-link', 'heading', 'scratch', 'scratch-inline', 'image-inline', 'glossary-link', 'video', 'interactive-tag', 'relative-link', 'image-container', 'table-of-contents'}))¶ Update the processors used for conversion with the given set. The updated set will be used for converting from this point onwards. If parameter is empty, default processors will be used.
Parameters: processors – A set of processor names given as strings for which their processors are enabled. If given, all other processors are skipped.
-
update_templates
(html_templates)¶ Update the template dictionary with the given dictionary of templates, while leaving all other HTML templates (including any custom set templates) untouched. The updated dictionary will be used for converting from this point onwards.
Parameters: html_templates – A dictionary of HTML templates to override existing HTML templates for processors. Dictionary contains processor names given as a string as keys mapping HTML strings as values. eg: {‘image’: ‘<img src={{ source }}>’}
-
-
class
verto.Verto.
VertoResult
¶ Object created by Verto containing the result data after a conversion by run.
-
html_string
¶ The converted HTML as a string.
-
title
¶ The text of the first heading found by the Save Title processor.
-
required_files
¶ A dictionary of files encountered in a Verto conversion. The dictionary has a string for the file type as the key (for example:
image
) and a set of all file paths encountered as the value (for example:{'image/face.png', 'image/logo.png`}
).
-
heading_tree
¶ A tuple of namedtuples which describes the tree of headings, as generated by our heading processor. Each namedtuple contains a title (string), title_slug (string), level (integer) and children (tuple of nodes).
-
required_glossary_terms
¶ A dictionary of terms to a list of tuples containing reference text and link IDs.
-