Importing Markdown (.md) content into Atlassian Confluence

When working with documentation, you often need to migrate content from Markdown files into Confluence. This can be a tedious process when done manually, especially with multiple files. I've created a Node.js script that automates this process, making the migration smooth and efficient.

Prerequisites

To use this script, you'll need:

1. Node.js installed on your computer
2. A Confluence workspace with appropriate permissions
3. An Atlassian API token here: https://id.atlassian.com/manage-profile/security/api-tokens
4. The following Node.js packages:
   • fs (built-in)
   • path (built-in)
   • marked
   • axios

Getting Started

Step 1: Set Up Your Project

First, create a new directory for your project and initialize it:

mkdir confluence-markdown-importer
cd confluence-markdown-importer
npm init -y
npm install marked axios

Step 2: Create Your Directory Structure

Create a folder named imports where you'll place all your Markdown files:

mkdir imports

Step 3: Set Up the Script

Create a file named import.js and paste the script below:

const fs = require('fs');
const path = require('path');
const marked = require('marked');
const axios = require('axios');

const markdownDir = path.join(__dirname, 'imports');
const confluenceBaseUrl = 'https://<YOUR_CONFLUENCE_INSTANCE>.atlassian.net';
const confluenceEmail = 'ATLASSIAN_EMAIL_ADDRESS';
const confluenceApiToken = 'ATLASSIAN_API_TOKEN';

(() => {
    
    const confluenceSpaceKey = 'YOUR_SPACE_KEY'; 

    const markdownFiles = fs.readdirSync(markdownDir).filter(file => file.endsWith('.md'));
    markdownFiles.forEach(async (file) => {
        try {
            const filePath = path.join(markdownDir, file);
            const markdownContent = fs.readFileSync(filePath, 'utf-8');
            
            const htmlContent = marked.parse(markdownContent);
            const pageTitle = `Ticket ${markdownContent.split('\n')[0].replace('## ', '').trim()}`;
            const payload = {
                type: 'page',
                space: { key: confluenceSpaceKey },
                title: pageTitle,
                body: {
                    storage: {
                        value: htmlContent,
                        representation: 'storage'
                    }
                }
            };
            
            const response = await axios.post(`${confluenceBaseUrl}/wiki/rest/api/content`, payload, {
                headers: {
                    'Content-Type': 'application/json',
                    'Accept': 'application/json',
                    Authorization: `Basic ${Buffer.from(`${confluenceEmail}:${confluenceApiToken}`).toString('base64')}`
                }
            });
            
            console.log(`Successfully imported: ${pageTitle}, page ID: ${response.data.id}`);

            await new Promise(resolve => setTimeout(resolve, 500));
        } 
        
        catch (error) {
            console.error(`Failed to import: ${file}`, 
                error.response?.data || error.message,
                '\nStatus:', error.response?.status,
                '\nHeaders:', JSON.stringify(error.response?.headers, null, 2));
        }
    });
})();

Step 4: Configure the Script

You'll need to replace several placeholder values in the script:

1. <YOUR_CONFLUENCE_INSTANCE> - Your Confluence instance name
2. ATLASSIAN_EMAIL_ADDRESS - The email address associated with your Atlassian account
3. ATLASSIAN_API_TOKEN - Your Atlassian API token (generate one at https://id.atlassian.com/manage-profile/security/api-tokens)
4. YOUR_SPACE_KEY - Your Confluence space key where pages will be created

To find your Space Key:

1. Log into your Confluence instance
2. Navigate to the desired space
3. Check the URL for the space key (e.g., .../spaces/SPACEKEY/...)
4. Alternatively, go to Space Settings and look under "Space Details"

Step 5: Add Your Markdown Files

Place your Markdown (.md) files in the imports directory. The script expects each file to have a heading that will be used as the page title.

Step 6: Run the Script

Execute the script with Node.js:

node import.js

The script will:

1. Read all Markdown files from the imports directory
2. Convert each file to HTML using the marked package
3. Create a new page in your Confluence space for each file
4. Output the results to the console

Important Notes

• The script introduces a 500ms delay between API calls to prevent rate limiting
• The page title is extracted from the first heading in your Markdown file
• Detailed error information is logged if an import fails
• You may need to adjust the script if your Markdown files have a different structure, but the markdown files tested used the following structure:

# Title

**Content**

*Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.*