Markdown Macro for Confluence - User Guide

Quick Start

Adding the Macro to Your Page

Edit a Confluence page
Type /markdown or click Insert → Other macros
Search for "Markdown" and select Markdown Content Development
Click to configure the macro

Creating Your First Markdown Content

The editor will open with a split-pane interface
Type your Markdown syntax in the left editor pane
See the live preview on the right side
Click Save when finished

Viewing Published Content

After saving, your Markdown content is rendered and displayed directly on the Confluence page. The published view shows your beautifully formatted content with:

Clean, professional typography
Properly rendered headings and text
Code blocks with syntax structure preserved
Tables, lists, and all Markdown elements displayed correctly

Interface Overview

The Markdown Editor features a professional dual-pane layout designed for efficient content creation.

Main Components

Component	Description

Component	Description
Toolbar	Quick access buttons for formatting (Headings, Format, Code, Lists, Tables, Links, Alerts, Structure)
Top Actions	Templates, Import, Export, Documentation, and Support buttons
Left Pane	Monaco-style Markdown editor with line numbers and syntax highlighting
Right Pane	Real-time preview showing rendered content
Bottom Actions	Cancel and Save buttons

Toolbar Features

The toolbar provides quick insertion buttons for common Markdown elements:

H Headings - Insert heading levels (H1-H6)
B Format - Bold, italic, strikethrough, inline code
Code - Code blocks with language selection
Lists - Unordered and ordered lists, task lists
Tables - Insert table structures
Links - Insert links and images
Alerts - Note, tip, warning, important callouts
Structure - Horizontal rules, blockquotes, collapsible sections

Adjustable Split Pane

The editor features a flexible split-pane layout that you can customize to match your workflow.

How to Adjust:

Drag the divider: Click and drag the vertical divider between the editor and preview panes to resize them
Double-click to reset: Double-click the divider to restore the default 50/50 split
Customize your workspace: Expand the editor for more writing space, or enlarge the preview for better visibility

Features

1. Real-Time Preview

As you type Markdown in the left pane, the right pane instantly renders the formatted content.

Key Benefits:

✅ Instant visual feedback
✅ Synchronized scrolling between editor and preview
✅ What-You-See-Is-What-You-Get experience

2. Syntax Highlighting

The editor supports syntax highlighting for code blocks in multiple languages including:

JavaScript, Python, Java, C++, C#
HTML, CSS, JSON, XML, YAML
Bash, SQL, and many more

3. Import Content

Import existing Markdown or HTML files directly into the editor.

How to Import:

Click the Import button in the top-right
Choose format:
- Markdown (.md) - Import Markdown files directly
- HTML (.html) - Import HTML files (automatically converted to Markdown)
Select your file (max 5MB)
Content appears in the editor ready for editing

Supported Formats:

.md - Markdown files
.html - HTML files (auto-converted)

4. Export Content

Export your Markdown content in multiple formats for portability.

How to Export:

Click the Export button in the top-right
Choose format:
- Markdown (.md) - Export as Markdown file
- HTML (.html) - Export as HTML file
File downloads to your device automatically

5. Template Library

Start quickly with professional templates for common documentation scenarios.

Available Templates:

Template	Description	Best For

Template	Description	Best For
Meeting Notes	Structured meeting minutes	Team meetings, standups
Project Documentation	Comprehensive project overview	Project kickoffs, planning
Requirements Document	Detailed functional requirements	Feature specs, PRDs
API Documentation	Standard API reference format	REST APIs, SDKs
Release Notes	Version release announcements	Product updates, changelogs
Bug Report	Systematic bug report template	QA, issue tracking
User Story	Agile user story format	Sprint planning
Post-Mortem	Incident analysis template	Incident reviews
Onboarding Guide	Employee onboarding checklist	HR, team onboarding
Technical Guide	Technical documentation structure	How-to guides, tutorials
Sprint Retrospective	Agile retrospective format	Sprint reviews
Changelog	Version history tracking	Release management

How to Use Templates:

Click Templates button
Browse the template gallery
Click on your desired template
Content is inserted into the editor
Customize as needed

Configuration

Editor Settings

The editor automatically saves your content when you click Save. Changes are stored with the Confluence page.

Line Numbers

Line numbers are displayed by default in the left margin to help navigate long documents.

FAQ

General Questions

Q: What Markdown syntax is supported? A: The macro supports full GitHub Flavored Markdown (GFM) including tables, task lists, code blocks with syntax highlighting, alerts, and more.

Q: Can I edit the macro after saving? A: Yes, simply click on the macro while editing the page, and it will reopen the editor with your existing content.

Q: Will my content be preserved if I cancel? A: If you click Cancel, any unsaved changes will be lost. Always click Save to preserve your work.

Import/Export

Q: What file formats can I import? A: You can import Markdown (.md) files directly, or HTML (.html) files which will be automatically converted to Markdown.

Q: What's the maximum file size for import? A: The maximum file size is 5MB for both Markdown and HTML imports.

Q: Can I export to other formats besides Markdown and HTML? A: Currently, the macro supports exporting to Markdown (.md) and HTML (.html) formats. For other formats, you can use external conversion tools.

Templates

Q: Can I create custom templates? A: Currently, the macro provides 12 pre-built professional templates. Custom template creation is not yet available but is planned for future releases.

Q: Are templates editable after insertion? A: Yes, templates provide a starting structure. You can fully edit, delete, or modify any template content after insertion.

Preview & Rendering

Q: Why does my preview look different from the saved content? A: The preview closely matches the final rendered output. Minor differences may occur due to Confluence's styling. If you notice significant differences, please contact support.

Q: Does the macro support emoji? A: Yes, you can use standard emoji syntax like :smile: or paste emoji directly.

Quick Reference

Markdown Syntax Cheatsheet