Using Verto

Using Verto to convert Markdown is a process of:

  1. Importing the installed Verto package.
  2. Creating a Verto converter.
  3. Passing Markdown text through the Verto convert method and saving the result object.
  4. 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. If processors 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 for image 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 is True.

    • 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 is True.

    • 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 and image-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 the alt argument as False 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 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).

    • 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.