- ` or `
-
Convert line breaks to
<br>
elements. -
Automatic conversion of entity data to HTML attributes (int & boolean to string,
style objecttostyle string). -
Wrapped blocks (
<li>elements go inside<ul>or<ol>).-
With arbitrary nesting.
-
Common text styles:
Bold
,
Italic
,
Underline
,
Monospace,Strikethrough.cmd + b -
Overlappingtext styles. Custom styles too!-
#hashtag
support via
#CompositeDecorators
.
- Linkify URLs too! http://example.com/
-
#hashtag
support via
#CompositeDecorators
.
- Depth can go back and forth, it works fiiine (1)
-
Common text styles:
Bold
,
Italic
,
Underline
,
-
Depth can go back and forth, it works fiiine (2)
- Depth can go back and forth, it works fiiine (3)
- Depth can go back and forth, it works fiiine (4)
-
With arbitrary nesting.
- Depth can go back and forth, it works fiiine (5)
- Import the library
- Define your configuration
-
Go!
- Optionally, define your custom components.
- ` elements go inside `
- ` or `
- `).
- With arbitrary nesting.
- Common text styles: **Bold**, *Italic*, Underline, `Monospace`, Strikethrough. cmd + b
- ~Overlapping \*\*te~**\*\**xt***\_ styles. \_Custom styles too!
- # hashtag support via [#CompositeDecorators](https://github.com/wagtail/draftjs_exporter/pull/17).
- Linkify URLs too!
- `, with multiple levels).
- Output inline styles as inline elements (``, ``, pick and choose, with any attribute).
- Overlapping inline style and entity ranges.
- Static type annotations.
It is developed alongside the [Draftail](https://www.draftail.org/) rich text editor, for [Wagtail](https://github.com/wagtail/wagtail). Check out the [online demo](http://playground.draftail.org/), and our [introductory blog post](https://www.draftail.org/blog/2018/03/13/rethinking-rich-text-pipelines-with-draft-js).
## When to use the exporter
[Draft.js](https://draftjs.org/) is a rich text editor framework for [React](https://reactjs.org/). Its approach is different from most rich text editors because it does not store data as HTML, but rather in its own representation called ContentState. This exporter is useful when the ContentState to HTML conversion has to be done in a Python ecosystem.
The initial use case was to gain more control over the content managed by rich text editors in a Wagtail/Django site. If you want to read the full story, have a look at our blog post: [Rethinking rich text pipelines with Draft.js](https://www.draftail.org/blog/2018/03/13/rethinking-rich-text-pipelines-with-draft-js).
## Where to go next
- **New to Draft.js?** Read [Content state](https://wagtail.github.io/draftjs_exporter/content-state/index.md) to understand the data model the exporter consumes.
- **Ready to render?** Follow [Getting started](https://wagtail.github.io/draftjs_exporter/getting-started/index.md) to install and render your first ContentState.
- **Configure the output.** See [Configuration](https://wagtail.github.io/draftjs_exporter/reference/configuration/index.md) for block, style, and entity maps.
- **Render as Markdown.** The exporter also produces [Markdown output](https://wagtail.github.io/draftjs_exporter/markdown/index.md).
- **Write custom components.** Use the React-like [custom components](https://wagtail.github.io/draftjs_exporter/guides/custom-components/index.md) API, or define [fallback components](https://wagtail.github.io/draftjs_exporter/guides/fallback-components/index.md) for missing block and entity types.
- **Pick an engine.** The default `string` engine is dependency-free. See [Alternative engines](https://wagtail.github.io/draftjs_exporter/guides/alternative-engines/index.md) for `html5lib` and `lxml`.
- **Find an error?** See [Troubleshooting](https://wagtail.github.io/draftjs_exporter/troubleshooting/index.md) for known issues and implementation details, and the [API reference](https://wagtail.github.io/draftjs_exporter/reference/api/index.md) for the full public API.
- **Upgrading?** See the [Migration guide](https://wagtail.github.io/draftjs_exporter/migration-guide/index.md) for breaking changes and upgrade steps by version.
## Contributing
See anything you like in here? Anything missing? We welcome all support, whether on bug reports, feature requests, code, design, reviews, tests, documentation, and more. Please have a look at our [contribution guidelines](https://wagtail.github.io/draftjs_exporter/CONTRIBUTING/index.md).
## Credits
Draftail was created by [Springload](https://github.com/springload/), and is now maintained by Wagtail contributors. View the full list of [contributors](https://github.com/wagtail/draftjs_exporter/graphs/contributors). MIT licensed.
# Getting started
Draft.js stores data in a JSON representation based on blocks, representing lines of content in the editor, annotated with entities and styles to represent rich text. To understand the data model in depth, read [Content state](https://wagtail.github.io/draftjs_exporter/content-state/index.md) first.
This exporter takes the Draft.js ContentState data as input, and outputs HTML based on its [configuration](https://wagtail.github.io/draftjs_exporter/reference/configuration/index.md). To get started, install the package:
```sh
pip install draftjs_exporter
```
We support the following Python versions: 3.10, 3.11, 3.12, 3.13, 3.14, 3.15. For legacy Python versions, find compatible releases in the [CHANGELOG](https://github.com/wagtail/draftjs_exporter/blob/main/CHANGELOG.md).
In your code, create an exporter and use the `render` method to produce HTML. Pass an empty config dict to use the default block, style, and entity maps — see [Configuration](https://wagtail.github.io/draftjs_exporter/reference/configuration/index.md) to customize them.
```python
from draftjs_exporter import HTML
exporter = HTML({})
html = exporter.render({
'entityMap': {},
'blocks': [{
'key': '6m5fh',
'text': 'Hello, world!',
'type': 'unstyled',
'depth': 0,
'inlineStyleRanges': [],
'entityRanges': []
}]
})
print(html)
```
For details on the ContentState structure of blocks / inline styles / entities, read [our content state overview](https://wagtail.github.io/draftjs_exporter/content-state/index.md).
You can also run an example by downloading this repository and then using `python example.py`, or by using our [online Draft.js demo](http://playground.draftail.org/).
> By default, the exporter uses a dependency-free `string` engine to build the DOM tree. If you need HTML escaping and sanitization, or have an existing `lxml`/`html5lib` setup, see [Alternative engines](https://wagtail.github.io/draftjs_exporter/guides/alternative-engines/index.md) to pick the right one.
## Type annotations
The exporter's codebase uses static type annotations, checked with mypy and ty. Reusable types are made available so you can annotate your own components:
```python
from draftjs_exporter import DOM, Element, Props
def image(props: Props) -> Element:
return DOM.create_element('img', {
'src': props.get('src'),
'width': props.get('width'),
'height': props.get('height'),
'alt': props.get('alt'),
})
```
See [Custom components](https://wagtail.github.io/draftjs_exporter/guides/custom-components/index.md) for the full component API.
## Next steps
- [Configuration](https://wagtail.github.io/draftjs_exporter/reference/configuration/index.md) – map Draft.js block types, styles, and entities to HTML.
- [Custom components](https://wagtail.github.io/draftjs_exporter/guides/custom-components/index.md) – render arbitrary markup from entity and block data.
- [API reference](https://wagtail.github.io/draftjs_exporter/reference/api/index.md) – the full public API.
- [Troubleshooting](https://wagtail.github.io/draftjs_exporter/troubleshooting/index.md) – known issues and implementation details.
# Content state
[Draft.js](https://draftjs.org/) stores rich text in a structured JSON representation called ContentState. The exporter takes this ContentState as input and converts it to HTML (or Markdown), based on its [configuration](https://wagtail.github.io/draftjs_exporter/reference/configuration/index.md). This page explains how Draft.js models content, so you know what to feed the exporter and what to expect from each block, entity, and inline style.
## How Draft.js represents rich text
Draft.js uses a fixed schema with predefined rich text types. There are strong constraints on content structure: what is block-level formatting, what is inline, what can carry data, and how. For storage and transport, Draft.js editors output a [raw ContentState](https://www.draftail.org/docs/next/draft-js/api-reference/data-conversion#converttoraw) representation that is serializable as JSON.
Here is a simple rich text example, in the shape you would pass it to the exporter. Each part of this structure is explained in the sections below.
```python
from draftjs_exporter import HTML
content_state = {
# All content is stored as a list of blocks, each representing a line.
"blocks": [
{
# Every block has a unique key, its text, and a type.
# "unstyled" is the default, used for plain paragraphs.
"key": "b1ito",
"text": "Example of the Draft.js ContentState.",
"type": "unstyled",
# Depth is greater than 0 when the block is nested (e.g. list items).
"depth": 0,
# Inline formatting is stored as ranges over the text.
# Ranges can overlap.
"inlineStyleRanges": [
{
# offset and length are character positions within `text`.
"offset": 15,
"length": 8,
"style": "BOLD",
},
],
# Entities (links, images, embeds) also use ranges, but cannot overlap.
# Each range points to an entry in `entityMap` by key.
"entityRanges": [
{
"offset": 24,
"length": 12,
"key": 0,
},
],
# Blocks can carry additional data (e.g. a blockquote's `cite` URL).
"data": {},
},
],
# The entity map holds the data for every entity referenced from blocks.
"entityMap": {
0: {
"type": "LINK",
# MUTABLE entities can be edited in place (like a link on text).
"mutability": "MUTABLE",
"data": {
"url": "https://www.draftail.org/docs/next/draft-js/api-reference/content-state",
},
},
},
}
# Pass the ContentState to the exporter's render method.
html = HTML({}).render(content_state)
```
## Blocks
Think of blocks as [block-level elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Block-level_elements) in HTML: headings, paragraphs, embeds, and so on. They direct the flow of the content, taking up the whole width of their containers and following one another vertically. All of the editor's content is stored in the `blocks` array.
Draft.js represents each block with the following attributes:
- `key`, a unique identifier for the block.
- `text`, the block's content in plain-text form.
- `type`, defining how the block behaves in the editor as well as how it should be displayed to end users.
- `depth`, whether the block is visually nested (for example in lists), and if so by how many levels.
- `inlineStyleRanges`, indicating where styles are applied in the text.
- `entityRanges`, indicating where entities are applied.
- `data`, additional data or metadata stored alongside the block.
## Block type
The block `type` generally defines how a block is meant to be used in the editor, and displayed later on in the content lifecycle. Blocks are `unstyled` by default.
Draft.js comes with predefined types, which generally map to HTML elements:
- `unstyled`
- `header-one`
- `header-two`
- `header-three`
- `header-four`
- `header-five`
- `header-six`
- `unordered-list-item`
- `ordered-list-item`
- `blockquote`
- `code-block`
- `atomic`, used for embedded, mostly non-textual content.
The exporter exposes these as the `BLOCK_TYPES` constants. See the [API reference](https://wagtail.github.io/draftjs_exporter/reference/api/index.md) for the full list, including the special `BLOCK_TYPES.FALLBACK` used to handle missing block types in your [configuration](https://wagtail.github.io/draftjs_exporter/reference/configuration/index.md).
## Inline styles
`inlineStyleRanges` lists all of the locations in the block's text where styles have been applied, based on starting `offset` and `length`. When multiple styles are applied to a given chunk of text, the ranges can overlap.
Draft.js comes with predefined inline styles:
- `BOLD`
- `CODE`
- `ITALIC`
- `STRIKETHROUGH`
- `UNDERLINE`
The exporter recognizes these as the `INLINE_STYLES` constants, and supports additional styles such as `SUPERSCRIPT`, `SUBSCRIPT`, and `KEYBOARD`. See the [API reference](https://wagtail.github.io/draftjs_exporter/reference/api/index.md) for the full list.
## Entities
Like for styles, `entityRanges` lists the positions in `text` where entities are applied as an `offset` and `length`. These cannot overlap. Entity ranges point to an entry in the `entityMap` by `key`.
In the `entityMap`, entities are stored as:
- `type`, like for blocks, defining how the entity behaves in the editor and how it should be displayed.
- `mutability` (`MUTABLE` or `IMMUTABLE`), whether changes in the text the entity is applied on are allowed (links on arbitrary text vs. mentions containing a person's full name, for example).
- `data`, to store arbitrary data for the entity.
The exporter exposes common entity categories as the `ENTITY_TYPES` constants (`LINK`, `IMAGE`, `HORIZONTAL_RULE`, and more). See the [API reference](https://wagtail.github.io/draftjs_exporter/reference/api/index.md) for the full list, including the special `ENTITY_TYPES.FALLBACK`.
## EditorState vs ContentState
ContentState is what Draft.js uses to represent the editor's content, but content is only one part of the editor's state. [`EditorState`](https://www.draftail.org/docs/next/draft-js/api-reference/editor-state) stores everything else: text selection, the undo/redo stack, and more.
The exporter only consumes ContentState. When an editor saves content, it converts its EditorState to a raw ContentState (the JSON shape above), and that is what you hand to [`HTML.render()`](https://wagtail.github.io/draftjs_exporter/reference/api/index.md). You do not need to handle EditorState on the Python side.
## Next steps
- [Getting started](https://wagtail.github.io/draftjs_exporter/getting-started/index.md) – render your first ContentState to HTML.
- [Configuration](https://wagtail.github.io/draftjs_exporter/reference/configuration/index.md) – map Draft.js block types, styles, and entities to HTML.
- [Custom components](https://wagtail.github.io/draftjs_exporter/guides/custom-components/index.md) – render arbitrary markup from entity and block data.
# Markdown support
> ⚠️ Markdown support is **experimental**. There is no guarantee of API stability at this time.
The exporter can render Draft.js content as Markdown in addition to HTML.
## Quick start
Use the built-in `MARKDOWN_CONFIG` to render Markdown with default settings. The config points the exporter at the Markdown DOM engine (`DOMMarkdown`), so `render` returns Markdown text instead of HTML:
```python
from draftjs_exporter import HTML, MARKDOWN_CONFIG
exporter = HTML(MARKDOWN_CONFIG)
markdown = exporter.render(content_state)
```
## Configuring output characters
Different Markdown processors and style guides prefer different syntax for the same constructs. Use `build_markdown_config` to choose which characters to use:
```python
from draftjs_exporter import HTML, build_markdown_config
config = build_markdown_config({
"bold": "__",
"italic": "*",
"unordered_list_marker": "*",
"ordered_list_delimiter": ")",
})
exporter = HTML(config)
```
All are optional. Omitted options use the defaults shown below. All defaults produce valid [CommonMark](https://commonmark.org/) output.
### Exporter output options
| Option | Choices | Default | Example output |
| ------------------------ | -------------------- | -------------------- | -------------- |
| `bold` | `**`, `__` | `**` | `**bold**` |
| `italic` | `*`, `_` | `_` | `_italic_` |
| `strikethrough` | `~`, `~~` | `~` | `~struck~` |
| `unordered_list_marker` | `-`, `*`, `+` | `-` | `- item` |
| `ordered_list_delimiter` | `.`, `)` | `.` | `1. item` |
| `horizontal_rule` | `---`, `***`, `___` | `---` | `---` |
| `code_fence` | ```` ``` ````, `~~~` | ```` ``` ```` | ```` ``` ```` |
| `block_fallback` | `Component`, `None` | Plain text + warning | |
| `entity_fallback` | `Component`, `None` | Plain text + warning | |
| `style_fallback` | `Component`, `None` | Plain text + warning | |
The three fallback options control what happens when the exporter encounters a block type, entity type, or inline style that has no explicit mapping. By default, each logs a warning and renders the content as plain text. Pass a custom `Component` function to change this behavior, or `None` to disable the fallback entirely.
```python
from draftjs_exporter import HTML, build_markdown_config
from draftjs_exporter.markdown.helpers import block
def my_block_fallback(props):
return block([" ", props["children"]])
config = build_markdown_config({
"block_fallback": my_block_fallback,
"style_fallback": None,
})
```
In this example, unknown blocks are prefixed with an HTML comment, while unknown styles raise an error instead of falling back to plain text.
## Default formatting
The following table shows every Draft.js content type the Markdown exporter handles, and its default Markdown output.
### Block types
| Draft.js block type | Markdown output |
| --------------------------------- | --------------------------------------------- |
| `unstyled` | Plain text followed by a blank line |
| `header-one` through `header-six` | `#` through `######` prefix |
| `blockquote` | `>` prefix |
| `unordered-list-item` | `-` prefix, with indent per depth level |
| `ordered-list-item` | `1.`, `2.`, etc., with indent per depth level |
| `code-block` | Wrapped in ```` ``` ```` fences |
### Inline styles
| Draft.js style | Markdown output |
| --------------- | --------------- |
| `BOLD` | `**text**` |
| `ITALIC` | `_text_` |
| `CODE` | `` `text` `` |
| `STRIKETHROUGH` | `~text~` |
### Entities
| Draft.js entity type | Markdown output |
| -------------------- | --------------- |
| `LINK` | `[text](url)` |
| `IMAGE` | `` |
| `HORIZONTAL_RULE` | `---` |
## Low-level API
For cases where `build_markdown_config` is not flexible enough, you can build a config dict manually from the individual component functions. This is the same approach used by the default `CONFIG` and `build_markdown_config` internally. The constants and default maps are available from the top-level package; the Markdown-specific component functions live in submodules:
```python
from draftjs_exporter import BLOCK_MAP as HTML_BLOCK_MAP, BLOCK_TYPES, ENTITY_TYPES, INLINE_STYLES, STYLE_MAP as HTML_STYLE_MAP
from draftjs_exporter.markdown.blocks import list_wrapper, make_ul, ol, prefixed_block
from draftjs_exporter.markdown.code import code_element, code_wrapper
from draftjs_exporter.markdown.entities import image, link, make_horizontal_rule
from draftjs_exporter.markdown.styles import inline_style
config = {
"engine": "draftjs_exporter.engines.markdown.DOMMarkdown",
"block_map": {
**HTML_BLOCK_MAP,
BLOCK_TYPES.UNSTYLED: prefixed_block(""),
BLOCK_TYPES.HEADER_ONE: prefixed_block("# "),
# ... other headings ...
BLOCK_TYPES.UNORDERED_LIST_ITEM: {
"element": make_ul("*"),
"wrapper": list_wrapper,
},
BLOCK_TYPES.ORDERED_LIST_ITEM: {
"element": ol,
"wrapper": list_wrapper,
},
BLOCK_TYPES.BLOCKQUOTE: prefixed_block("> "),
BLOCK_TYPES.CODE: {
"element": code_element,
"wrapper": code_wrapper,
},
},
"style_map": dict(
HTML_STYLE_MAP,
**{
INLINE_STYLES.BOLD: inline_style("__"),
INLINE_STYLES.CODE: inline_style("`"),
INLINE_STYLES.ITALIC: inline_style("*"),
INLINE_STYLES.STRIKETHROUGH: inline_style("~~"),
},
),
"entity_decorators": {
ENTITY_TYPES.IMAGE: image,
ENTITY_TYPES.LINK: link,
ENTITY_TYPES.HORIZONTAL_RULE: make_horizontal_rule("***"),
},
}
```
## Unsupported
The Markdown exporter has inherent limitations compared to the HTML exporter.
- **No underline, subscript, or other HTML-only styles**: The exporter’s default configuration falls through to inline HTML like `text`.
- **No reference-style links**: Links are always rendered inline as `[text](url)`.
- **No table support**: Draft.js has no built-in table block type, and the exporter does not attempt to generate Markdown tables from custom block types.
- **No Setext-style headings**: Headings always use ATX style (`# Heading`).
- **Entity data fidelity**: The Markdown link syntax `[text](url)` only preserves the URL.
- **No HTML escaping in text**: If your Draft.js content contains literal HTML characters like like `<` or `>`, the Markdown output will include them unescaped, which may be interpreted as HTML by Markdown renderers.
- **Inline style nesting edge cases**: When bold and italic styles partially overlap, the exporter may produce markers that some strict Markdown parsers reject (e.g. `**Bold **_Italic_**`). Most renderers handle this correctly, but it is not guaranteed by the CommonMark spec.
# Migration guide
This page collects the upgrade notes for each major (and selected minor) release of the exporter. Each section describes the breaking changes and the steps to follow when upgrading from the previous version. For the full list of changes in each release, see the [CHANGELOG](https://github.com/wagtail/draftjs_exporter/blob/main/CHANGELOG.md).
## Upgrading to v6.0.0
### Python 3.7, 3.8, and 3.9 support removed
Python 3.7, 3.8, and 3.9 are no longer supported. For projects still on these versions, keep using [v5.2.0](https://github.com/wagtail/draftjs_exporter/tree/v5.2.0).
### Cleaner nested inline style output
The exporter now produces fewer redundant tags in nested and partially nested inline style output. For example, a bold range covering `[0-11]` and an italic range covering `[5-11]` now produce `Bold Italic` rather than `Bold Italic`. The output is semantically equivalent but produces different HTML. If your code or tests compare exact output strings, update them. See [Troubleshooting](https://wagtail.github.io/draftjs_exporter/troubleshooting/#exporter-behavior) for details.
### lxml lower bound raised
The lower bound of the optional `lxml` dependency is now `>=4.6.5`. If you use the `lxml` engine, make sure your installed version meets this requirement.
## Upgrading to v5.0.0
### Python 3.6 support removed
Python 3.6 is no longer supported, as it has reached its [end of life](https://www.python.org/dev/peps/pep-0494/). For projects needing Python 3.6, keep using [v4.1.2](https://github.com/wagtail/draftjs_exporter/tree/v4.1.2).
### New `string_compat` engine
A new `string_compat` engine is available for maximum output stability. It produces identical output to the first release of the `string` engine, with no backwards-incompatible changes since. To use it, set the `engine` property in your config:
```python
config = {
'engine': DOM.STRING_COMPAT,
}
```
If you relied on the old `string` engine's output and it changed in a way that breaks your tests, switch to `string_compat` to restore the previous behavior. See [Alternative engines](https://wagtail.github.io/draftjs_exporter/guides/alternative-engines/index.md) for the full list of engines.
## Upgrading to v4.0.0
### Python 3.5 support removed
Do not upgrade to this version if you are using the exporter in Python 3.5. Keep using [v3.0.1](https://github.com/wagtail/draftjs_exporter/tree/v3.0.1).
### HTML attributes no longer sorted alphabetically (string engine)
The default `string` engine no longer sorts attributes alphabetically by name in its output HTML. This makes it possible to control the order of attributes as needed, wherever attributes are specified:
```python
def image(props):
return DOM.create_element('img', {
'src': props.get('src'),
'width': props.get('width'),
'height': props.get('height'),
'alt': props.get('alt'),
})
```
If you relied on alphabetical sorting, you can either reorder your `props` / `wrapper_props` / `create_element` calls as needed, or subclass the built-in `string` engine and override its `render_attrs` method to add back the sort:
```python
@staticmethod
def render_attrs(attr: Attr) -> str:
attrs = [f' {k}="{escape(v)}"' for k, v in attr.items()]
attrs.sort()
return "".join(attrs)
```
### HTML quotes no longer escaped outside attributes (string engine)
The default `string` engine no longer escapes single and double quotes in HTML content (it still escapes quotes inside attributes). If you relied on this behavior, subclass the built-in `string` engine and override its `render_children` method to add back `quote=True`:
```python
@staticmethod
def render_children(children: Sequence[Union[HTML, Elt]]) -> HTML:
return "".join(
[
DOMString.render(c)
if isinstance(c, Elt)
else escape(c, quote=True)
for c in children
]
)
```
### Inline style properties no longer sorted alphabetically
The exporter supports passing the `style` attribute as a dictionary with JS-style property names, and automatically converts it to a CSS string. The properties are no longer sorted alphabetically — you can now reorder the dictionary's keys to control the output order.
If you relied on alphabetical sorting, either reorder the keys as needed, or pass the `style` as a string (with standard CSS property syntax).
## Upgrading to v3.0.0
### Python 2.7 and 3.4 support removed
Do not upgrade to this version if you are using the exporter in Python 2.7 or 3.4. Keep using [v2.1.7](https://github.com/wagtail/draftjs_exporter/tree/v2.1.7).
### PEP-484 type annotations
The exporter now ships with [PEP-484](https://www.python.org/dev/peps/pep-0484/) type annotations on its public API. If your codebase uses a type checker, there is a chance these annotations will create conflicts with your project's annotations — if there are discrepancies between the expected input/output of the exporter, or in the configuration. In this case, update your project's type annotations or stubs to match the expected types of the exporter's public API.
If you believe there is a problem with how the public API is typed, [open a new issue](https://github.com/wagtail/draftjs_exporter/issues/new/choose).
## Upgrading to v2.0.0
### New default engine
The default DOM engine changed from `html5lib` to `string` (a dependency-free engine). To start using the new default:
1. Remove the `engine` property from the exporter configuration, or set `'engine': DOM.STRING,`.
1. You can also remove the `html5lib` and `beautifulsoup4` dependencies from your project if they aren't used anywhere else.
To keep using the previous default (html5lib):
1. Set the `engine` property to `'engine': DOM.HTML5LIB,`.
1. Make sure you install the exporter with `pip install draftjs_exporter[html5lib]`.
See [Alternative engines](https://wagtail.github.io/draftjs_exporter/guides/alternative-engines/index.md) for the details of each engine.
### Decorator component definitions
Class-based decorators are no longer supported. Decorator components now require the function syntax (see [Custom components](https://wagtail.github.io/draftjs_exporter/guides/custom-components/index.md)):
```python
# Before:
class OrderedList:
def render(self, props):
depth = props['block']['depth']
return DOM.create_element('ol', {
'class': f'list--depth-{depth}'
}, props['children'])
# After:
def ordered_list(props):
depth = props['block']['depth']
return DOM.create_element('ol', {
'class': f'list--depth-{depth}'
}, props['children'])
```
If you were relying on the configuration capabilities of the class API, switch to composing components instead:
```python
# Before:
class Link:
def __init__(self, use_new_window=False):
self.use_new_window = use_new_window
def render(self, props):
link_props = {'href': props['url']}
if self.use_new_window:
link_props['target'] = '_blank'
link_props['rel'] = 'noreferrer noopener'
return DOM.create_element('a', link_props, props['children'])
# In the config:
ENTITY_TYPES.LINK: Link(use_new_window=True)
# After:
def link(props):
return DOM.create_element('a', props, props['children'])
def same_window_link(props):
return DOM.create_element(link, {
'href': props['url'],
}, props['children'])
def new_window_link(props):
return DOM.create_element(link, {
'href': props['url'],
'target': '_blank',
'rel': 'noreferrer noopener',
}, props['children'])
```
Composite decorators also changed to a dict format with `strategy` and `component` keys, matching Draft.js:
```python
# Before:
class BR:
SEARCH_RE = re.compile(r'\n')
def render(self, props):
if props['block']['type'] == BLOCK_TYPES.CODE:
return props['children']
return DOM.create_element('br')
'composite_decorators': [BR]
# After:
def br(props):
if props['block']['type'] == BLOCK_TYPES.CODE:
return props['children']
return DOM.create_element('br')
'composite_decorators': [
{'strategy': re.compile(r'\n'), 'component': br},
]
```
See the [Configuration reference](https://wagtail.github.io/draftjs_exporter/reference/configuration/index.md) for the current composite decorators format.
### Engine configuration
The `engine` field in the exporter config now requires a dotted-path string pointing to a valid engine, rather than a short name. Use the `DOM` class constants as shorthand:
```diff
'engine': 'html5lib',
+ 'engine': DOM.HTML5LIB,
```
It is no longer possible to directly provide an engine class — use a dotted path instead:
```diff
DOM.use(DOMTestImpl)
+ DOM.use('tests.test_dom.DOMTestImpl')
```
## Upgrading to v1.1.0
### String engine opt-in
This release adds a new string-based, dependency-free DOM engine. There is no need to make any changes to keep using the previous engines (`html5lib`, `lxml`). To switch to the new `string` engine, opt in via the config:
```diff
exporter = HTML({
+ 'engine': 'string',
})
```
The new engine is faster than both `html5lib` and `lxml`, and outputs functionally identical HTML. Its only drawback is that `DOM.parse_html()` provides no safeguards against malformed or unescaped HTML, whereas `lxml` or `html5lib` sanitize the input. See [Alternative engines](https://wagtail.github.io/draftjs_exporter/guides/alternative-engines/index.md) for details.
## Upgrading to v0.9.0
### Composite decorators block type access
The block type for composite decorators has moved from `props['block_type']` to `props['block']['type']`:
```diff
- props['block_type']
+ props['block']['type']
```
### Removed DOM methods
The following DOM methods have been removed:
- `DOM.get_children()` — no longer available.
- `DOM.pretty_print()` — no longer available.
### ConfigException moved
`ConfigException` moved to `draftjs_exporter.error`:
```diff
- from draftjs_exporter.options import ConfigException
+ from draftjs_exporter.error import ConfigException
```
### `className` prop no longer auto-converted to `class`
The exporter no longer automatically converts a `className` prop to a `class` attribute. Use `class` directly:
```diff
- BLOCK_TYPES.BLOCKQUOTE: ['blockquote', {'className': 'c-pullquote'}]
+ BLOCK_TYPES.BLOCKQUOTE: ['blockquote', {'class': 'c-pullquote'}]
```
## Upgrading to v0.8.0
This release overhauled the block and style mapping format. Most declarations need updating.
### Block mapping format
Element-only block declarations can now use a plain string instead of a dict:
```diff
- BLOCK_TYPES.HEADER_TWO: {'element': 'h2'},
+ BLOCK_TYPES.HEADER_TWO: 'h2',
```
Array-style block declarations are replaced with the `element` / `props` format:
```diff
- BLOCK_TYPES.BLOCKQUOTE: ['blockquote', {'class': 'c-pullquote'}]
+ BLOCK_TYPES.BLOCKQUOTE: {'element': 'blockquote', 'props': {'class': 'c-pullquote'}}
```
Block wrapper declarations no longer use array syntax:
```diff
- 'wrapper': ['ul', {'class': 'bullet-list'}],
+ 'wrapper': 'ul',
+ 'wrapper_props': {'class': 'bullet-list'},
```
### Style mapping format
Style declarations follow the same format as block declarations:
```diff
- 'KBD': {'element': 'kbd'},
+ 'KBD': 'kbd',
```
```diff
- 'HIGHLIGHT': {'element': 'strong', 'textDecoration': 'underline'},
+ 'HIGHLIGHT': {'element': 'strong', 'props': {'style': {'textDecoration': 'underline'}}},
```
The default style map changed `STRIKETHROUGH` to the `s` tag and `UNDERLINE` to the `u` tag. To restore the previous behavior, define them explicitly:
```python
'STRIKETHROUGH': {'element': 'span', 'props': {'style': {'textDecoration': 'line-through'}}},
'UNDERLINE': {'element': 'span', 'props': {'style': {'textDecoration': 'underline'}}},
```
### Exception location
`BlockException` was renamed to `ConfigException` and moved:
```diff
- from draftjs_exporter.wrapper_state import BlockException
+ from draftjs_exporter.options import ConfigException
```
### `camel_to_dash` moved
```diff
- from draftjs_exporter.style_state import camel_to_dash
- camel_to_dash()
+ from draftjs_exporter.dom import DOM
+ DOM.camel_to_dash()
```
### Code block default rendering
Code blocks are now rendered inside both `pre` and `code` tags by default. To keep the previous behavior, use the new `PRE` block type:
```diff
- BLOCK_TYPES.CODE: 'pre',
+ BLOCK_TYPES.CODE: lambda props: DOM.create_element('pre', {}, DOM.create_element('code', {}, props['children'])),
+ BLOCK_TYPES.PRE: 'pre',
```
### Entity props
Entities now receive the content of their `data` dict directly as props, instead of the whole entity map:
```diff
def render(self, props):
- data = props.get('data', {})
link_props = {
- 'href': data['url'],
+ 'href': props['url'],
}
```
### Removed DOM methods
The following DOM methods have been removed:
- `DOM.create_text_node(text)` — use the text string directly instead.
- `DOM.create_document_fragment()` — use `DOM.create_element()` instead.
- `DOM.get_text_content(elt)` — no longer available.
- `DOM.set_text_content(elt, text)` — no longer available.
# Guides
# Custom components
To generate arbitrary markup with dynamic data, the exporter comes with an API to create rendering components. This API mirrors React's [createElement](https://facebook.github.io/react/docs/top-level-api.html#react.createelement) API (what JSX compiles to). Components are referenced from your [configuration](https://wagtail.github.io/draftjs_exporter/reference/configuration/index.md) under `block_map`, `style_map`, and `entity_decorators`.
All of the API is available from a single `DOM` namespace:
```python
from draftjs_exporter import DOM
```
Components are simple functions that take a `props` dict as parameter and return DOM elements. The shape of `props` depends on what the component is rendering: entities, blocks, or inline styles each pass different data.
## Entity components
Entity components render things like links, images, or embeds. They receive the entity's `data` dict as `props`. For example, an `IMAGE` entity whose Draft.js `data` is `{"src": ..., "width": ..., "height": ..., "alt": ...}` can be rendered as an `
- ` or `
- `:
```python
BLOCK_TYPES.UNORDERED_LIST_ITEM: {
'element': 'li',
'wrapper': 'ul',
'wrapper_props': {'class': 'bullet-list'},
},
```
For more flexibility — reading block data or depth — point the `element` at a [custom component](https://wagtail.github.io/draftjs_exporter/guides/custom-components/index.md) instead of a tag name:
```python
BLOCK_TYPES.BLOCKQUOTE: blockquote,
BLOCK_TYPES.ORDERED_LIST_ITEM: {
'element': list_item,
'wrapper': ordered_list,
},
```
## Style map
`style_map` defines the HTML representation of inline styles. It uses the same mapping format as `block_map`: a string for the simplest case, a dict to add props.
```python
config = {
'style_map': {
**STYLE_MAP,
'KBD': 'kbd',
'HIGHLIGHT': {'element': 'strong', 'props': {'style': {'textDecoration': 'underline'}}},
},
}
```
The `style` prop can be a string (rendered as-is) or a dict, in which case its properties are converted to a CSS string using `camel_to_dash`.
## Entity decorators
`entity_decorators` maps entity types to components so they can be rendered with their data. Each value is a [custom component](https://wagtail.github.io/draftjs_exporter/guides/custom-components/index.md) function, a lambda, or `None` to discard that entity type entirely.
```python
config = {
'entity_decorators': {
ENTITY_TYPES.IMAGE: image,
ENTITY_TYPES.LINK: link,
ENTITY_TYPES.HORIZONTAL_RULE: lambda props: DOM.create_element('hr'),
ENTITY_TYPES.EMBED: None,
},
}
```
## Composite decorators
Composite decorators replace text based on a regular expression. Use them for line breaks, mentions, linkification, or any text-level transformation that isn't an entity in the Draft.js data.
Each entry is a dict with a `strategy` (compiled regex) and a `component` (a [custom component](https://wagtail.github.io/draftjs_exporter/guides/custom-components/index.md) function):
```python
config = {
'composite_decorators': [
{'strategy': re.compile(r'\n'), 'component': br},
{'strategy': re.compile(r'#\w+'), 'component': hashtag},
{'strategy': LINKIFY_RE, 'component': linkify},
],
}
```
## Fallbacks
Each map accepts a special fallback key — `BLOCK_TYPES.FALLBACK`, `INLINE_STYLES.FALLBACK`, or `ENTITY_TYPES.FALLBACK` — that is triggered when the exporter encounters a type with no explicit mapping. See [Fallback components](https://wagtail.github.io/draftjs_exporter/guides/fallback-components/index.md) for how to write one.
## Putting it all together
See [`example.py`](https://github.com/wagtail/draftjs_exporter/blob/main/example.py) as a fully-fledged demo of the configuration. For the full list of block types, inline styles, and entity types the exporter recognizes, see the [API reference](https://wagtail.github.io/draftjs_exporter/reference/api/index.md).
# Example output (generated by `example.py`)
## HTML
```html
draftjs_exporter is an HTML exporter for Draft.js content
Try it out by running this file!
Features 📝🍸
The exporter aims to provide sensible defaults from basic block types and inline styles to HTML, that can easily be customized when required. For more advanced scenarios, an API is provided (mimicking React's
createElement
) to create custom rendering components of arbitrary complexity.
Here are some features worth highlighting:
For developers 🚀
def blockquote(props):
block_data = props['block']['data']
return DOM.create_element('blockquote', {
'cite': block_data.get('cite')
}, props['children'])
Render as
div
Voilà!
``` ## Markdown ## draftjs_exporter is an HTML exporter for [Draft.js](https://github.com/facebook/draft-js) content > Try it out by running this file! ### Features 📝🍸 The exporter aims to provide sensible defaults from basic block types and inline styles to HTML, that can easily be customized when required. For more advanced scenarios, an API is provided (mimicking React's [`createElement`](https://facebook.github.io/react/docs/top-level-api.html#react.createelement)) to create custom rendering components of arbitrary complexity. ______________________________________________________________________ Here are some features worth highlighting: - Convert line breaks to `` elements. - Automatic conversion of entity data to HTML attributes (int & boolean to string, [`style object` to `style string`](https://facebook.github.io/react/docs/jsx-in-depth.html)). - Wrapped blocks (`