If you’ve ever needed to get your HTML into Jira or Confluence, you know the process isn’t exactly straightforward. Atlassian uses its own JSON-based document model called Atlassian Document Format (ADF). While ADF is flexible and powerful, generating it from HTML can be a hassle.

Fortunately, there are a few NPM libraries that attempt to bridge the gap and convert HTML into ADF. In this post, we’ll walk through what’s out there today, and also show you an alternative if you’d rather not spend time running and maintaining these libraries yourself.

---

1. @atlaskit/adf-utils

Atlassian’s own utilities package comes with helpers for working with ADF. While it’s not primarily designed for HTML conversion, some developers hack together HTML-to-ADF pipelines by mixing adf-utils with HTML parsers like cheerio. This works, but it’s a lot of manual mapping—you’ll spend time writing your own rules to handle tags, styles, and nested content.

Pros: Official, well-maintained, good for manipulating ADF.

Cons: Doesn’t directly convert HTML → ADF, lots of custom code required.

---

2. html-to-adf

This community-built package provides a direct way to transform HTML strings into ADF JSON. It works for simple cases like paragraphs, headings, lists, and links. But depending on your content, you may run into gaps (e.g., tables, complex inline formatting).

Pros: Simple, focused, does what it says.

Cons: Limited coverage, not actively maintained, may require patching.

---

3. @guardian/html-to-adf

The Guardian’s engineering team open-sourced their own converter. It’s a more complete take on the problem, supporting a wider range of HTML tags and structures. However, since it was built for their internal workflows, you may need to adapt it for your own use cases.

Pros: Stronger coverage, from a reputable dev team.

Cons: Somewhat tied to their needs, not plug-and-play for every scenario.

---

4. Roll-Your-Own with prosemirror-model

Since ADF is a close cousin of ProseMirror’s schema, some teams bypass HTML conversion libraries entirely and build a pipeline using prosemirror-model + custom HTML parsing. This approach gives you total control—but it’s also the most complex.

Pros: Maximum flexibility, full schema control. Cons: High effort, not recommended unless you have deep ProseMirror experience.

---

5. An Alternative to Self-Hosting

If you’re comfortable managing dependencies, self-hosting one of the libraries above can work well. You’ll get full control and the ability to customize the conversion logic to your exact needs.

But for many teams, the overhead of installing, maintaining, and patching these tools isn’t worth it—especially if conversion is just one small part of a larger workflow.

That’s where a hosted option can help. Instead of running your own converter, you can call an API and get back clean, valid ADF without worrying about infrastructure or updates. All of the above options require you to:

• Install and maintain NPM dependencies
• Patch edge cases when tags don’t convert cleanly
• Keep up with updates in ADF’s evolving schema

For internal tools or one-off conversions, this might be fine. But if you need reliable, production-grade HTML → ADF conversion without the maintenance headache, you might want to look at a hosted option.

That’s exactly why we built adfapi.dev. Instead of worrying about dependencies or schema mismatches, you can:

• Send your HTML via API
• Get back clean, valid ADF
• Skip the infrastructure, just use it wherever you need it

Perfect if you want to integrate conversions into apps, scripts, or CI pipelines without owning the complexity.

---

Final Thoughts

If you’re exploring HTML → ADF, the libraries above will give you a starting point. They’re worth experimenting with if you want full control and don’t mind the upkeep. But if your goal is simply to get reliable conversions today, adfapi.dev is the fastest path forward. Try out the live demo or sign up for an API key to see how easy it can be.