Rightdown

an open-source Markdown dialect

with a reference implementation in Python

Why Rightdown?

Rightdown:

  • is almost syntactically identical to markdown

    • every markdown file is already a rightdown file

  • has a modern, class-based Python implementation that:

    • parses rightdown files into a true in-memory graph structure
    • can hand you all the metadata, fields, taxonomies, and links embedded in a document
    • allows fragmented documents, each fragment with individual metadata, fields, etc.

  • has CSS guidelines for rendering

Using Rightdown

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.

Writing Rightdown

For now, please see our older Markdown Style Guide.

We’ll get the rightdown-specific version of this content online really soon.

  • files & fragments
  • blocks
  • inlines

TODO – get these pages online…

Advanced Features

class RightDownData

The RightDownData class has several useful methods:

Processing

.Process(text, **options)
(class method) Digests a string of text, returns a RightDownData instance

Rendering

.Text()
Renders the rightdown content out as rightdown content
.Html()
Renders the content out as HTML

Structured Data

.Metadata(html=False)
Returns a dictionary of structured data from the (invisible) YAML prefix
.Fields(html=False)
Returns a dictionary of structured data from (visible) tuples and definition lists
.Links(html=False)
Returns a list of (name, target) tuples for links
.Taxonomies(html=False)
Returns a list of tree-like structures, like bullet and number lists

class 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

Fragmented Files

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.

Back to Octoboxy

Octoboxy