0 Fork 0

Files

T

james.maes 4810c80390 feat(core): implement Markdown to Confluence publisher

- Confluence Cloud API client with auth, CRUD, attachments, labels
- Tree builder with glob matching, title extraction, hierarchy mapping
- Markdown to Confluence Storage Format converter
- Publisher orchestration with idempotent updates via content hash
- CLI and GitHub Action stubs

2025-12-17 17:04:11 -06:00

1.4 KiB

Raw Permalink Blame History

Forma

Publish Markdown documentation to Confluence. Keep your docs in Git, publish to Confluence automatically.

Features

Directory structure becomes Confluence page hierarchy
Multi-root mapping: publish multiple directories to different Confluence parents
Idempotent updates via content properties (not title-based)
Local lint command catches issues before publish
GitHub Action for CI/CD integration
Relative link conversion between pages
Attachment upload (images, PDFs)
Mermaid diagram support (auto-detects macro availability)

Installation

npm install -g forma-cli

Usage

# Lint locally (no API calls)
forma lint

# Preview changes
forma plan

# Publish to Confluence
forma publish

Configuration

Create .confluence-publish.yml in your repo root:

version: 1

confluence:
  baseUrl: "https://YOURDOMAIN.atlassian.net/wiki"
  spaceKey: "DOCS"

mappings:
  - localRoot: "docs/architecture"
    parentPageTitle: "Architecture"
  - localRoot: "docs/guides"
    parentPageTitle: "Guides"

publish:
  include: ["**/*.md"]
  exclude: ["**/node_modules/**", "**/.git/**"]

GitHub Action

- uses: kof22/forma@v1
  env:
    CONFLUENCE_EMAIL: ${{ secrets.CONFLUENCE_EMAIL }}
    CONFLUENCE_API_TOKEN: ${{ secrets.CONFLUENCE_API_TOKEN }}

Project Structure

packages/
  publisher/    # Core library
  cli/          # CLI (forma command)
action/         # GitHub Action

License

MIT

1.4 KiB Raw Permalink Blame History