md-confluence

A Node.js library and CLI tool to publish markdown files to Atlassian Confluence.

Features

• 🚀 Publish single markdown files or multiple files using configuration
• 📝 Converts markdown to Confluence storage format
• 🔄 Only updates pages when content has changed (uses SHA256 hashing)
• 🎯 Supports custom code block rendering for Confluence
• 📦 Available as both a library and CLI tool
• ✨ TypeScript-ready with JSDoc annotations

Installation

Global Installation (CLI usage)

npm install -g md-confluence

Local Installation (library usage)

npm install md-confluence

CLI Usage

Environment Variables

Set these environment variables:

export CONFLUENCE_DOC_EMAIL="[email protected]"
export CONFLUENCE_DOC_TOKEN="your-api-token"
export CONFLUENCE_URL="https://your-company.atlassian.net"

Commands

Publish multiple pages using default pages.json

md-confluence

Publish multiple pages using custom config file

md-confluence --config pages.json

Publish single file

md-confluence --file README.md --page-id 123456789

Use custom Confluence URL

md-confluence --url https://mycompany.atlassian.net

Show help

md-confluence --help

Configuration File Format

Create a pages.json file mapping Confluence page IDs to markdown files:

{
  "123456789": "README.md",
  "987654321": "docs/api-guide.md",
  "456789123": "docs/deployment.md"
}

Library Usage

Basic Example

import { ConfluenceConfig, publishMarkdownToConfluence } from 'md-confluence';

const config = new ConfluenceConfig({
  userEmail: '[email protected]',
  apiToken: 'your-api-token',
  confluenceUrl: 'https://your-company.atlassian.net',
  repoUrl: 'https://github.com/your-org/your-repo' // optional
});

const result = await publishMarkdownToConfluence(
  '123456789', // Confluence page ID
  './README.md', // Path to markdown file
  config
);

console.log(result);

Publish Multiple Pages

import { ConfluenceConfig, publishMultiplePages } from 'md-confluence';

const config = new ConfluenceConfig({
  userEmail: '[email protected]',
  apiToken: 'your-api-token',
  confluenceUrl: 'https://your-company.atlassian.net'
});

const pageMapping = {
  '123456789': 'README.md',
  '987654321': 'docs/api-guide.md'
};

const results = await publishMultiplePages(pageMapping, config);
console.log(results);

Convert Markdown Only

import { convertMarkdownToConfluence } from 'md-confluence';

const markdownContent = '# Title\n\nSome content';
const { title, html } = convertMarkdownToConfluence(markdownContent);

console.log('Title:', title);
console.log('HTML:', html);

API Reference

ConfluenceConfig

Configuration class for Confluence connection.

const config = new ConfluenceConfig({
  userEmail: 'string',      // Required
  apiToken: 'string',       // Required  
  confluenceUrl: 'string',  // Required
  repoUrl: 'string'         // Optional
});

Functions

• publishMarkdownToConfluence(pageId, filePath, config, options) - Publish single file
• publishMultiplePages(pageMapping, config, options) - Publish multiple files
• convertMarkdownToConfluence(markdown, options) - Convert markdown to Confluence format
• getLatestVersion(pageId, config) - Get latest version of Confluence page
• updateContent(contentBody, config) - Update Confluence page content
• calculateContentHash(content) - Calculate SHA256 hash of content
• loadPagesConfig(configPath) - Load pages configuration from JSON file

Development

Install Dependencies

npm install

Run Tests

npm test
npm run test:coverage
npm run test:watch

Lint Code

npm run lint
npm run lint:fix

Run CLI in Development

npm run dev  # Shows help
npm start -- --help  # Also shows help

Getting Confluence API Token

1. Go to Atlassian Account Settings
2. Click "Create API token"
3. Give it a label and click "Create"
4. Copy the token (you won't be able to see it again)

Getting Confluence Page ID

1. Go to your Confluence page
2. Click "..." → "Page Information"
3. The page ID is in the URL: /pages/viewinfo.action?pageId=PAGE_ID

License

MIT

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run tests and linting
6. Submit a pull request