Add ADF passthrough via <adf> tags - #7
Conversation
- Document context, options, and rationale for <adf> tag passthrough approach Co-Authored-By: opencode <noreply@opencode.ai>
- Add expected ADF output for mixed markdown + embedded extension macro Co-Authored-By: opencode <noreply@opencode.ai>
- 10 tests: happy path (object + array), error cases, non-regression - 9 expected to fail until feature is implemented Co-Authored-By: opencode <noreply@opencode.ai>
- Add parseAdfTag helper to parse and validate embedded ADF JSON - Handle html tokens in tokensToAdf, returning node(s) directly - Supports single object or array input; throws on invalid JSON or missing type Co-Authored-By: opencode <noreply@opencode.ai>
- Add braces to case "html" to properly scope const declaration - Add non-null assertion on match[1] to express regex invariant Co-Authored-By: opencode <noreply@opencode.ai>
- Add 'Embedding ADF nodes' section to README with usage example - Add v1.2.0 entry to CHANGELOG - Bump version in lib/package.json to 1.2.0 Co-Authored-By: opencode <noreply@opencode.ai>
- Fix AVA import style to match existing test files, eliminating TS noise - Add empty <adf> tag guard with clear error message - Add tests for empty tag and inline (non-block) placement behaviour - Document block-level requirement in README Co-Authored-By: opencode <noreply@opencode.ai>
✅ Deploy Preview for marklassian ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
jamsinclair
left a comment
jamsinclair
left a comment
There was a problem hiding this comment.
Thanks for the contribution @merphx! This looks like a great addition.
For such a small library I would rather avoid introducing AI generated ADR documents to avoid context rot. I believe the README changes, CHANGELOG and tests should provide ample context for any human or LLM agent.
Please let me know if you or your team have any other feature requests!
|
Published to NPM - https://www.npmjs.com/package/marklassian/v/1.2.0 |
|
Cheers @jamsinclair ! Good feedback, thanks. I'll note that for future PRs (and I'll need to think about that for my own projects as well). Coming up soonish on my radar is adding support to convert in the other direction: ADR → Markdown (using I'm keen to enhance the Atlassian tools that we're building for OpenCode so that it shows a human-readable diff to the developer before publishing changes to Confluence/Atlassian—and to minimise the misery factor I'd like it to show the diff as Markdown rather than ADF 😸 |
2 participants
Summary
Enable embedding raw ADF nodes directly inside Markdown by wrapping them in
<adf>…</adf>tags. This lets coding agents — and highly detail-oriented human authors, I suppose 😸 — mix standard Markdown with arbitrary ADF constructs (macros, panels, status badges, Confluence extensions, etc.) in a singlemarkdownToAdf()call, without changing the public API.The primary use case is coding agents using Markdown so humans can easily review the content before publishing but needing to include ADF for macros that don't have Markdown equivalents; the tag acts as a thin passthrough layer with no new syntax for the coding agent to learn.
This has been field-tested in production use to create and edit real Confluence pages and Jira work items. Very pleased with the results 🤩
Changes
markdownToAdfnow handleshtmltokens containing<adf>…</adf>tags. The inner content is parsed as a JSON ADF node (or array of nodes) and inserted directly into the output. Any other HTML block continues to be ignored.typestrings throw a descriptive error at conversion time.docs/adr/001-adf-passthrough-syntax.mdrecords the design options considered and the rationale for the chosen approach.Versioning note
In the PR I included a minor version bump (1.1.0 → 1.2.0) as a suggestion: no breaking changes are introduced, and
<adf>is not a standard or proposed HTML element, making tag name collisions with valid Markdown+HTML inputs extremely unlikely.If you'd prefer, I'm happy to pull the version bump, changelog, etc. out of the PR; LMK.
Reviewer notes
<adf>[{…}, {…}]</adf>) is supported for multi-node embeddings. I wasn't sure whether coding agents would actually do this, but it was super simple to add support for it.markedand silently ignored. Adapting this would have required more substantial changes to the library which would have felt a bit heavy-handed for this change.