# madfun
## `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
<hr/>
Would you like to use `Ma`rkdown to post `A`tlassian `D`ocument `F`ormatted
content while still having `fun`? Then this tool's for you!
### How It Works
`madfun` works by taking input in
[Markdown](https://www.markdownguide.org/), either as text or a parsed
abstract syntax tree
([AST](https://en.wikipedia.org/wiki/Abstract_syntax_tree)) and converting
it to an `adf:Node` tree that conforms to Atlassian's
[ADF](https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/).
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:
```rust
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:
```rust
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.
License: MIT OR Apache-2.0