djblets.markdown.extensions.wysiwyg¶

Markdown extension to render content similar to the source.

This will render Markdown such that the spacing and alignment in the source text and the rendered content looks roughly the same. It’s meant to help ensure that what’s typed is very close to what’s viewed when rendered.

class SmartEmptyBlockProcessor(parser)[source]¶

Bases: 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: 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.

LAZY_OL = False[source]¶

run(parent, blocks)[source]¶

Run the processor on the given blocks.

__annotations__ = {}¶

class TrimTrailingEmptyParagraphs(md=None)[source]¶

Bases: 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 TrimmedRawHtmlPostprocessor(md=None)[source]¶

Bases: 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 more efficiently replaces the raw HTML placeholders and ensures there are no trailing newlines in the resulting HTML. Not only does it prevent the newline normally added by the original function, but it strips trailing newlines from stashed HTML that may have been generated by other extensions, keeping spacing consistent and predictable.

run(text)[source]¶

Run the processor on the HTML.

Parameters:

text (unicode) – The text to process.

Returns:

The processed text.

Return type:

unicode

__annotations__ = {}¶

class WysiwygFormattingExtension(**kwargs)[source]¶

Bases: 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)[source]¶

Extend the list of Markdown processors.

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

Parameters:

md (markdown.Markdown) – The Markdown instance.

__annotations__ = {}¶

makeExtension(*args, **kwargs)[source]¶

Create and return an instance of this extension.

Parameters:

• *args (tuple) – Positional arguments for the extension.

• **kwargs (dict) – Keyword arguments for the extension.

Returns:

The extension instance.

Return type:

WysiwygFormattingExtension