Skip to main content

Crate madfun

Crate madfun 

Source
Expand description

§madfun

WARNING: This crate is incomplete, and does not include full support for all Markdown blocks. Known working Markdown primitives:

  • code
  • inlinecode
  • links
  • paragraphs
  • text

Would you like to use Markdown to post Atlassian Document Formatted content while still having fun? Then this tool’s for you!

§How It Works

madfun works by taking input in Markdown, either as text or a parsed abstract syntax tree (AST) and converting it to an adf:Node tree that conforms to Atlassian’s ADF. This type implements serde’s Serialize and Deserialize traits, so it’s easy to convert to a JSON representation via serde_json.

Once you’ve got that, it should be simple (lol) to use any HTTP or Atlassian client to send it wherever it’s going.

§Usage

The core of madfun is the ToAdf trait; this exposes methods for converting text or pre-parsed Markdown (via the markdown crate) into a serde_json::Value that can then be serialized as you desire.

If you have Markdown text:

let adf = madfun::from_str(
    "Here is my Markdown content",
).unwrap();

If you’ve already got the Markdown parsed into a markdown::mdast::Node, then you can use the infallible ToAdf::to_adf method:

use madfun::ToAdf;

let mdast = markdown::to_mdast(
    "Here is my Markdown content",
    &markdown::ParseOptions::default(),
).unwrap();

let adf = mdast.to_adf();

§Limitations

madfun is currently unidirectional; it takes Markdown and renders ADF JSON. Unfortunately, it can’t (yet?) take ADF as returned from the Atlassian APIs and convert it back to Markdown, though in theory this should be doable (if not actually isomorphic).

§Roadmap

  • Clean up/improve the crate interface
    • Add to/from reader/writer functions
  • Better error messages
  • Complete full translation of Markdown -> ADF
  • Finish isomorphic (where possible) Markdown <-> ADF capabilities
  • Maybe add support for pulldown-cmark as a Markdown parser?

§LICENSE

madfun is dual-licensed as MIT or Apache-2.0. Have fun.

Modules§

adf

Structs§

ParseOptions
Configuration that describes how to parse from markdown.

Enums§

Error

Traits§

ToAdf

Functions§

from_str
Generate ADF from Markdown text.
to_markdown
Errors