Rightdown:
is almost syntactically identical to markdown
has a modern, class-based Python implementation that:
has CSS guidelines for rendering
Rightdown is part (half) of a PyPi project called “OctoBase”.
Assuming any reasonable Python v3.x environment, install with pip
:
$ sudo pip install base
From then, turning a string of markdown text into HTML is as easy as:
import base
text = '***every markdown file is _already_ a rightdown file***'
html = base.RightDownData.Process(text).Html()
print(html)
The result should look like:
<!DOCTYPE html>
<html>
<head><meta charset="utf-8"></head>
<body>
<section><p><b><i>every markdown file is <u>already</u> a rightdown file</i></b></p></section>
</body>
</html>
Whoops! Our string was wrapped in a whole HTML document. This is probably correct, but not quite what we expected. Instead, let’s do this:
html = base.RightDownData.Process(text, html_add_head=False).Html()
print(html)
The result now should be:
<section><p><b><i>every markdown file is <u>already</u> a rightdown file</i></b></p></section>
That’s better.
For now, please see our older Markdown Style Guide.
We’ll get the rightdown-specific version of this content online really soon.
TODO – get these pages online…
RightDownData
The RightDownData
class has several useful methods:
.Process(text, **options)
.Text()
.Html()
.Metadata(html=False)
.Fields(html=False)
.Links(html=False)
(name, target)
tuples for links.Taxonomies(html=False)
RightDownOptions
The other high-level class is RightDownOptions
, which lets you adjust how parsing and rendering are done.
For example, say you’re building a rightdown editor, and you need to render into HTML but also preserve the rightdown style marks at the same time. There is a flag for this, and you can specify it in a couple different places.
Method 1:
html = base.RightDownData.Process(text, html_include_formatting=True).Html()
Method 2:
with base.RightDownOptions(html_include_formatting=True):
html = base.RightDownData.Process(text).Html()
These two methods are equivalent. When using the with
syntax, options are cumulative, so this works as you would expect:
with base.RightDownOptions(html_add_head=False):
with base.RightDownOptions(html_include_formatting=True):
html = base.RightDownData.Process(text).Html()
For a full list of options, see the file base/rightdown/highlevel.py
A rightdown document is divided into fragments at hard-break lines (---
in markdown syntax). Each fragment in a document can be rendered or have structured metadata extracted separate from the others.
Each of the above RightDownData
methods also accepts an optional argument fragment
, which takes a zero-based integer for the fragment you want to access.