3
0
mirror of https://github.com/larvit/adf-codec.git synced 2026-11-20 07:05:44 +01:00

Human updated README

This commit is contained in:
2026-11-08 10:38:58 +01:00
committed by Lillem4n
parent 185bbac83c
commit be3872de0a
+15 -18
View File
@@ -3,28 +3,25 @@
[![npm](https://img.shields.io/npm/v/@larvit/adf-codec)](https://www.npmjs.com/package/@larvit/adf-codec) [![npm](https://img.shields.io/npm/v/@larvit/adf-codec)](https://www.npmjs.com/package/@larvit/adf-codec)
[![CI](https://github.com/larvit/adf-codec/actions/workflows/ci.yml/badge.svg)](https://github.com/larvit/adf-codec/actions/workflows/ci.yml) [![CI](https://github.com/larvit/adf-codec/actions/workflows/ci.yml/badge.svg)](https://github.com/larvit/adf-codec/actions/workflows/ci.yml)
Convert Atlassian Document Format (ADF), the rich text of Jira and Confluence, to and from markdown, Convert between ADF (Atlassian Document Format) and other formats.
with a lossless round-trip, and to HTML.
This package is pure functions with no React, no Atlaskit and no runtime dependencies, and nothing to ## Main functionality
configure or connect. It runs in Node, Forge, Deno, Bun and browsers.
It is for application developers whose app shows, edits, exports or generates the rich text Atlassian * **portableMarkdownToAdf** Use this if you "just have markdown". It reads CommonMark plus GFM's tables, task lists and alerts, ~~, and Obsidians's callouts and ==; `commonMarkToAdf` reads strict CommonMark alone.
products store as ADF. * **commonMarkToAdf** Strict CommonMark parser to ADF. Will return an error if not strictly CommonMark.
* **adfToLosslessMarkdown** Converts ADF to adf-codecs own flavour of markdown to accommodate to ADFs specials like panels, mentions, statuses etc, as well as carrying unkown future ADF nodes to always guarantee a way to losslessly convert between ADF and Markdown.
* **losslessMarkdownToAdf** The reverse roundtrip from the function above.
* **adfToHtml** ADF to HTML.
* **htmlToAdf** HTML to ADF.
| You have | You want | Take | What it does | ## Features and perks
| --- | --- | --- | --- |
| Markdown from a bot, a model or a person | ADF | `portableMarkdownToAdf` | reads CommonMark plus GFM's tables, task lists and alerts, `~~`, and Obsidian's callouts and `==`; `commonMarkToAdf` reads strict CommonMark alone |
| ADF | markdown to edit, then ADF again | `adfToLosslessMarkdown`, then `losslessMarkdownToAdf` | the pair gives back the document it started from, panels, mentions, statuses and node types this version does not know included |
| ADF | markdown that GitHub, GitLab and Obsidian render | `adfToPortableMarkdown` | keeps the text, images by URL and link targets and drops the rest |
| ADF | HTML | `adfToHtml` | writes paragraphs, headings, lists, quotes, tables, code blocks, rules, breaks, a plain external image, links, and code, emphasis and strong text as HTML elements, and every other node as an element holding its JSON; `htmlToAdf` reads that HTML back to the same document, and refuses any other HTML |
Every call returns a result, never a throw. A refusal carries a code from a closed list, and the same input gets the same refusal, except * No runtime dependencies.
for `engine-limit` ([The guarantees](#the-guarantees)). * No React, no Atlaskit.
TypeScript types ship beside the JavaScript. * Runs on Node, Forge, Deno, Bun and browsers.
* Nothing to configure or connect.
Atlaskit's markdown transformer converts markdown to ADF, and its ADF to markdown throws. * All errors are returned, never thrown.
[Other ADF converters](#other-adf-converters) compares this package with it and the rest. * All errors are known and documented so you can make a complete implementation with all error handling pre-handled.
## Install ## Install