djblets.markdown.extensions.wysiwyg¶

class SmartEmptyBlockProcessor(parser)[source]¶

Bases: markdown.blockprocessors.BlockProcessor

Handles empty blocks in a more specialized way.

By default, Python-Markdown will trim away excess empty blocks, with the idea being that it doesn’t matter how much whitespace exists between tags when rendered to HTML. However, in our case, we need to preserve whitespace in order to better match the resulting render to the input text.

We replace any empty lines with paragraph tags, which will safely stick around.

This is invoked before EmptyBlockProcessor.

test(parent, block)[source]¶

Test that the processor should apply to the given block.

run(parent, blocks)[source]¶

Run the processor on the given blocks.

class PreserveStartOListBlockProcessor(parser)[source]¶

Bases: markdown.blockprocessors.OListProcessor

Applies CSS styles to any <ol> with a start= attribute.

This allows for CSS tricks to be performed that ensure that ordered list item numbers and item contents line up between source text and rendered text. It basically turns off the <li>’s native counter value and instead creates its own using :before and CSS counters. These tricks end up causing the start= attribute on the <ol> to be ignored.

This block processor extends the standard OListProcessor to also apply a CSS style to set the displayed counter value to the intended start value.

This replaces OListProcessor.

run(parent, blocks)[source]¶

Run the processor on the given blocks.

class TrimTrailingEmptyParagraphs(markdown_instance=None)[source]¶

Bases: markdown.treeprocessors.Treeprocessor

Removes empty paragraphs from the end of the tree.

This will remove any trailing empty paragraphs formerly added by SmartEmptyBlockProcessor. This step must be done after all the blocks are processed, so that we have a complete picture of the state of the tree. It’s therefore performed right before we prettify the tree.

run(root)[source]¶

Run the processor on the root of the tree.

class RTrimmedString[source]¶

Bases: unicode

Keeps a string free of trailing whitespace when replacing.

This is used in TrimmedRawHtmlPostprocessor to prevent the base RawHtmlPostprocessor code from adding an extra unnecessary newline when replacing raw HTML placeholders.

When that code calls replace(), the replaced contents will be rstrip’d, removing the newline. The result of that call is another RTrimmedString.

Note that other functions may result in a standard string being returned, but in the case of RawHtmlPostprocessor, this isn’t really a concern.

replace(src, dest)[source]¶

Replace the contents of the string.

This wraps the string’s replace method to return another RTrimmedString instead of a standard string, rstripping any newlines in the process.

class TrimmedRawHtmlPostprocessor(markdown_instance=None)[source]¶

Bases: markdown.postprocessors.RawHtmlPostprocessor

Post-processes raw HTML placeholders, without adding extra newlines.

Python Markdown’s RawHtmlPostprocessor had a nasty habit of adding an extra newline after replacing a placeholder with stored raw HTML. That would cause extra newlines to appear in our output.

This version first converts the string to a RTrimmedString, preventing these newlines from being added. It then converts back to a standard string.

run(text)[source]¶

Run the processor on the HTML.

class WysiwygFormattingExtension(configs={})[source]¶

Bases: markdown.extensions.Extension

Provides a series of WYSIWYG formatting rules for Markdown rendering.

We have a lot of specific rendering concerns that Python Markdown doesn’t really address, or generally need to care about. We try very hard to match up newlines around various code blocks, and we have special ways we do ordered lists. The resulting rendered output is meant to look identical to the input text, as much as possible.

This extension renders a series of processors that ensures that the HTML output is in the format required for our rendering.

This is meant to be used with the following Markdown configuration and extensions:

{
    'lazy_ol': False,
    'extensions': [
        'sane_lists', 'nl2br', 'djblets.markdown.extentions.wysiwyg',
    ],
}

extendMarkdown(md, md_globals)[source]¶

Extend the list of Markdown processors.

Each processor in this file will be registered in the order necessary for the smarter formatting.

makeExtension(configs={})[source]¶

Create a Markdown extension instance for this file.