Pages created via cfl use legacy editor format

[piekstra]

Description

Pages created using cfl page create are being created in Confluence's legacy editor format rather than the new cloud editor format.

Observed Behavior

When creating a page via the CLI:

echo "# My Page" | cfl page create -s ENG -t "My Page"

The resulting page shows:

• A "Legacy editor" badge in the page header
• Tooltip: "This page is using the legacy editor"
• A prompt to "Convert page" to the cloud editor

Expected Behavior

Pages should be created using the new Confluence cloud editor format by default, since Atlassian has announced the legacy editor will be phased out.

Screenshots

(See attached screenshots showing the legacy editor indicator and conversion prompt)

Near Title:

When Clicking "Edit":

Environment

• cfl version: (latest)
• Confluence Cloud

Additional Context

From the Confluence UI, there's a modal stating:

"Time to convert your page. This page is compatible with the cloud editor. The legacy editor will be phased out soon, find out more in the announcement."

This suggests the API may need to use a different endpoint or parameter to create pages in the new format.

[rianjs]

Research Notes: Legacy vs Cloud Editor

Root Cause

Pages created via cfl page create use the storage representation (XHTML), which results in legacy editor pages. The cloud editor uses Atlassian Document Format (ADF) - a JSON structure.

Relevant API Endpoints

Purpose	Endpoint	Notes
Check editor version	GET /rest/api/content/{id}?expand=metadata.properties.editor	Returns v2 for cloud, v1 or absent for legacy
Read page as ADF	GET /api/v2/pages/{id}?body-format=atlas_doc_format	Returns ADF in body.atlas_doc_format.value (JSON string)
Convert to v2	PUT /rest/api/content/{id}/convert?hash=13	Undocumented but referenced in community
Set editor property	Page properties API	Set editor property to v2
Create with ADF	POST /api/v2/pages with body.atlas_doc_format	Value must be JSON-stringified ADF

ADF Structure

{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "paragraph",
      "content": [
        {"type": "text", "text": "Hello world"}
      ]
    }
  ]
}

Key node types:

• Block: paragraph, heading, bulletList, orderedList, codeBlock, blockquote, table, rule
• Inline: text, hardBreak, inlineCard
• Marks: strong, em, code, link, strike, underline

Test Strategy (Proposed)

Use Atlassian's own conversion as ground truth:

1. Create pages via CLI (legacy format)
2. Convert to v2 (via API or UI)
3. Read back with body-format=atlas_doc_format
4. Use captured ADF as test fixtures for our Markdown→ADF converter

Sources

• Create page with atlas_doc_format
• Struggling to create with new editor
• Find editor version via API
• ADF Structure docs

[rianjs]

Implementation Strategy (from discussion with @rianjs)

Phased Approach

Phase 1: Test Infrastructure
Before writing any feature code, establish a robust test foundation:

1. Migrate existing tests to --legacy flag

   • Current integration tests for page create and page edit should continue to work
   • Move these tests under a --legacy flag context
   • Ensures backwards compatibility is maintained

2. Capture ground-truth ADF from Atlassian

   • Create test pages via CLI (produces legacy format)
   • Convert pages to v2 editor (via UI or convert API)
   • Read pages back with body-format=atlas_doc_format
   • This gives us Atlassian-generated ADF as our test fixtures

3. Build test suite for ADF output

   • Unit tests: Markdown → ADF conversion for each content type
   • Integration tests: Create page with ADF, verify it opens in cloud editor
   • Round-trip tests: Create → Read → Verify structure

Content Types to Test

• Simple paragraphs
• Headings (h1-h6)
• Text formatting (bold, italic, strikethrough, inline code)
• Links (external URLs, internal page links)
• Lists (bullet, numbered, nested)
• Code blocks (with language annotation)
• Tables (GFM format)
• Blockquotes
• Horizontal rules
• Images/attachments
• Combinations of the above

Key Insight

"We can be clever here to get known-good ADF data" - by using the integration tests to create pages, then converting them and reading back, we get Atlassian's own conversion as our source of truth. This avoids guessing at ADF structure.

Flags Design

• Default: Cloud editor (ADF format)
• --legacy: Use storage format (XHTML) for backwards compatibility
• Both page create and page edit should support this flag

[rianjs]

ADF Reference: Real Examples from Confluence

Captured from live Confluence pages (all v2/cloud editor format).

Simple Text

{"type": "paragraph", "content": [{"text": "Hello world", "type": "text"}]}

Headings

{"type": "heading", "attrs": {"level": 1}, "content": [{"text": "Title", "type": "text"}]}
{"type": "heading", "attrs": {"level": 2}, "content": [{"text": "Subtitle", "type": "text"}]}

Text Formatting (via marks array)

// Bold
{"text": "bold text", "type": "text", "marks": [{"type": "strong"}]}

// Italic
{"text": "italic text", "type": "text", "marks": [{"type": "em"}]}

// Combined
{"text": "bold and italic", "type": "text", "marks": [{"type": "strong"}, {"type": "em"}]}

Links

{
  "text": "Link text",
  "type": "text",
  "marks": [{"type": "link", "attrs": {"href": "https://example.com"}}]
}

Bullet List

{
  "type": "bulletList",
  "content": [
    {"type": "listItem", "content": [
      {"type": "paragraph", "content": [{"text": "First item", "type": "text"}]}
    ]},
    {"type": "listItem", "content": [
      {"type": "paragraph", "content": [{"text": "Second item", "type": "text"}]}
    ]}
  ]
}

Ordered List

{
  "type": "orderedList",
  "attrs": {"order": 1},
  "content": [
    {"type": "listItem", "content": [
      {"type": "paragraph", "content": [{"text": "First", "type": "text"}]}
    ]}
  ]
}

Code Block

{"type": "codeBlock", "content": [{"text": "code here", "type": "text"}]}

// With language:
{"type": "codeBlock", "attrs": {"language": "python"}, "content": [{"text": "print('hi')", "type": "text"}]}

Blockquote

{
  "type": "blockquote",
  "content": [
    {"type": "paragraph", "content": [{"text": "Quoted text", "type": "text"}]}
  ]
}

Horizontal Rule

{"type": "rule"}

Table

{
  "type": "table",
  "attrs": {"layout": "default"},
  "content": [
    {"type": "tableRow", "content": [
      {"type": "tableHeader", "attrs": {"colspan": 1, "rowspan": 1}, "content": [
        {"type": "paragraph", "content": [{"text": "Header", "type": "text"}]}
      ]}
    ]},
    {"type": "tableRow", "content": [
      {"type": "tableCell", "attrs": {"colspan": 1, "rowspan": 1}, "content": [
        {"type": "paragraph", "content": [{"text": "Cell", "type": "text"}]}
      ]}
    ]}
  ]
}

Document Wrapper

All content wrapped in:

{"type": "doc", "version": 1, "content": [...]}

Key Observations

1. Text nodes always have type: "text" and text: "content"
2. Formatting uses marks array on text nodes
3. Block elements contain content arrays
4. List items always wrap content in paragraph nodes
5. Tables use tableHeader for first row, tableCell for others
6. Code blocks don't require language attribute
7. version: 1 at document root

[rianjs]

Key Experimental Finding: Storage→ADF Conversion Limitations

Created a test page via CLI (storage format) and read it back as ADF. Important discovery:

What Worked

• Headings → heading with correct level
• Bold/italic → text with marks array (strong, em)
• Inline code → text with code mark
• Bullet lists → bulletList structure
• Numbered lists → orderedList structure
• Blockquotes → blockquote
• Horizontal rules → rule
• Links → text with link mark

What Didn't Work

Code blocks - Our HTML <pre><code class="language-python">...</code></pre> got converted to:

{"type": "paragraph", "content": [{"text": "print(\"hello\")\n", "type": "text", "marks": [{"type": "code"}]}]}

Instead of a proper:

{"type": "codeBlock", "attrs": {"language": "python"}, "content": [{"text": "print(\"hello\")", "type": "text"}]}

Implication

If we want proper codeBlock elements, we must send ADF directly - we cannot rely on Confluence's storage→ADF conversion to preserve code blocks correctly.

This confirms the need for a proper Markdown→ADF converter rather than just switching the API representation format.

[rianjs]

Plan: Cloud Editor (ADF) Support for Issue #39

Summary

Implement native Atlassian Document Format (ADF) support so pages created via cfl use the cloud editor by default, with a --legacy flag for backwards compatibility.

Research Findings (see issue #39 comments)

• Pages created with storage format (HTML) → legacy editor
• Pages created with atlas_doc_format (ADF) → cloud editor
• Confluence's storage→ADF conversion loses code block structure
• Conclusion: Need proper Markdown→ADF converter, not just format switch

Implementation Phases

Phase 1: Test Infrastructure

Goal: Establish test foundation before any feature code.

1. Capture ADF test fixtures (pkg/md/testdata/adf/)

   • paragraph.json - basic paragraph
   • heading.json - h1 through h6
   • formatting.json - bold, italic, code, strikethrough
   • links.json - external links
   • bullet_list.json - bullet lists including nested
   • ordered_list.json - numbered lists
   • code_block.json - with and without language
   • blockquote.json
   • horizontal_rule.json
   • table.json - GFM tables
   • combined.json - complex document with multiple elements

2. Create unit test framework (pkg/md/to_adf_test.go)

   • Table-driven tests for each markdown element
   • Input: markdown string
   • Expected: ADF JSON structure
   • Leverage captured fixtures as expected output

Phase 2: Markdown→ADF Converter

Goal: Convert markdown to valid ADF.

1. Create pkg/md/to_adf.go

   • Parse markdown with goldmark (reuse existing parser)
   • Walk AST and emit ADF nodes
   • Return JSON string (double-encoded as Confluence expects)

2. ADF node types to implement:

   Markdown	ADF Type
   paragraph	paragraph
   # heading	heading with attrs.level
   bold	text with strong mark
   italic	text with em mark
   code	text with code mark
   link	text with link mark
   - item	bulletList → listItem
   1. item	orderedList → listItem
   ```lang	codeBlock with attrs.language
   > quote	blockquote
   ---	rule
   | table |	table → tableRow → tableCell

3. Document structure:

   {"type": "doc", "version": 1, "content": [...]}

Phase 3: API Integration

Goal: Wire up ADF creation in page commands.

1. Modify api/types.go

   • CreatePageRequest.Body already supports AtlasDocFormat
   • No changes needed to types

2. Modify internal/cmd/page/create.go

   • Add --legacy flag (default: false)
   • When --legacy: use existing storage format path
   • When not --legacy: convert markdown→ADF, use atlas_doc_format

3. Modify internal/cmd/page/edit.go

   • Same --legacy flag logic
   • Handle reading existing page content (may need to read as ADF)

Phase 4: Integration Tests

Goal: Verify end-to-end behavior.

1. New integration test cases (integration-tests.md):

   • Create page (default) → opens in cloud editor
   • Create page --legacy → opens in legacy editor
   • Edit page (default) → stays in cloud editor
   • Edit page --legacy → stays in legacy editor
   • Create with code blocks → verify proper codeBlock in ADF

2. Editor version check: Use v1 API to verify editor property

Files to Modify/Create

File	Action
pkg/md/to_adf.go	CREATE - Markdown→ADF converter
pkg/md/to_adf_test.go	CREATE - Unit tests
pkg/md/testdata/adf/*.json	CREATE - Test fixtures
internal/cmd/page/create.go	MODIFY - Add --legacy flag
internal/cmd/page/edit.go	MODIFY - Add --legacy flag
integration-tests.md	MODIFY - Add cloud editor tests

Verification

1. Unit tests: go test -v ./pkg/md/...
2. Integration test:

   # Create page (cloud editor)
   echo "# Test" | ./bin/cfl page create -s confluence -t "[Test] Cloud Editor"
   # Verify in browser: should NOT show "legacy editor" badge
   
   # Create page (legacy)
   echo "# Test" | ./bin/cfl page create -s confluence -t "[Test] Legacy" --legacy
   # Verify in browser: should show "legacy editor" badge

3. API verification:

   curl -u "$EMAIL:$TOKEN" "$URL/rest/api/content/{id}?expand=metadata.properties.editor"
   # Cloud editor: editor.value = "v2"
   # Legacy: editor = null or "v1"

Open Questions (resolved through experiments)

• ✅ Can we read ADF from existing pages? Yes - ?body-format=atlas_doc_format
• ✅ Does storage→ADF conversion work? Partially - code blocks don't convert properly
• ✅ What ADF structure does Confluence expect? Documented in issue Pages created via cfl use legacy editor format #39 comments

Dependencies

• goldmark (existing) - for markdown parsing
• No new external dependencies required

[rianjs]

Implementation Complete

Cloud editor (ADF) support has been implemented. Summary of changes:

New Files

• pkg/md/to_adf.go - Markdown→ADF converter
• pkg/md/to_adf_test.go - Unit tests (22 test cases)
• pkg/md/testdata/adf/*.json - Test fixtures

Modified Files

• internal/cmd/page/create.go - Default to ADF, added --legacy flag
• internal/cmd/page/edit.go - Default to ADF, added --legacy flag
• internal/cmd/page/create_test.go - Updated tests, added ADF tests
• internal/cmd/page/edit_test.go - Updated tests, added ADF tests
• integration-tests.md - Added cloud editor verification docs

Behavior

• Default: Pages created/edited use cloud editor format (ADF)
• --legacy flag: Use legacy editor format (XHTML storage)

ADF Features Implemented

• Paragraphs, headings (h1-h6)
• Bold, italic, code, strikethrough
• Links
• Bullet lists, ordered lists, nested lists
• Code blocks with language highlighting
• Blockquotes
• Horizontal rules
• Tables (GFM format)

Verification

Created test page via CLI → confirmed ADF structure with proper codeBlock node (not paragraph with code mark) → confirmed no "Legacy editor" badge in browser.

Ready for review and merge.

[rianjs]

Test Coverage Audit & Plan

Current State

File	Tests	Coverage
create_test.go	10	File input only, missing stdin/editor
edit_test.go	10	File input only, missing stdin/editor
to_adf_test.go	14	Good element coverage, missing validation

Critical Gaps

1. Input Source Coverage

• ✗ Stdin input (both ADF and legacy paths)
• ✗ Editor mode (interactive editing)

2. Flag Combination Matrix

                    --legacy    --no-markdown    Combined
File (.md)            ✓              ✓              ✓
File (.html)          ✓              -              -
Stdin                 ✗              ✗              ✗
Editor                ✗              ✗              ✗

3. Round-Trip Scenarios (none tested)

• Create (ADF) → Edit (ADF)
• Create (ADF) → Edit (legacy)
• Create (legacy) → Edit (ADF)
• Create (legacy) → Edit (legacy)

Planned Unit Tests

create_test.go (+6 tests):

• TestRunCreate_Stdin_ADF
• TestRunCreate_Stdin_Legacy
• TestRunCreate_Stdin_NoMarkdown_ADF
• TestRunCreate_Stdin_NoMarkdown_Legacy
• TestRunCreate_EmptyContent
• TestRunCreate_ComplexMarkdown_ADF

edit_test.go (+6 tests):

• TestRunEdit_Stdin_ADF
• TestRunEdit_Stdin_Legacy
• TestRunEdit_TitleAndContent
• TestRunEdit_TitleOnly_PreservesBody
• TestRunEdit_RoundTrip_ADF_to_ADF
• TestRunEdit_RoundTrip_Legacy_to_Legacy

to_adf_test.go (+6 tests):

• TestToADF_OutputIsValidJSON
• TestToADF_Images_AltText
• TestToADF_WhitespaceInCodeBlock
• TestToADF_TableAlignment
• TestToADF_NestedBlockquote
• TestToADF_HardLineBreak

Design Decision

Format mismatch: Warn but proceed when editing ADF page with --legacy flag.

Integration Tests

Will add comprehensive test matrix and round-trip verification to integration-tests.md.

[rianjs]

Integration Test Results ✅

All cloud editor (ADF) integration tests passed.

Test	Result	Notes
CE-01: stdin → ADF	✅	Proper ADF structure with heading, paragraph, bulletList
CE-02: stdin → storage (--legacy)	✅	Created with storage format
CE-03: file.md → ADF	✅	File input works with ADF
CE-04: file.md → storage (--legacy)	✅	File input works with legacy
RT-01: ADF → Edit → ADF	✅	ADF structure preserved after edit
RT-03: ADF → Edit with --legacy	✅	Warning shown: ⚠ Using --legacy flag...
Code block preservation	✅	Proper codeBlock node with language: "go"

Verification Details

ADF Structure Verified:

{
  "type": "codeBlock",
  "attrs": { "language": "go" },
  "content": [{ "text": "func main() {...}", "type": "text" }]
}

Format Mismatch Warning:

⚠ Using --legacy flag. If this page uses the cloud editor, it may switch to the legacy editor.

All test pages cleaned up after testing.