Liftmark documentation

Get started

1. Install Liftmark from the Atlassian Marketplace (Confluence admin). Sites of up to 10 users pay a flat $8 a month, and every site gets a 30-day free trial.
2. Open Apps > Liftmark. The Start here tab explains the three parts of the app and where to find each one.
3. Open the page you want to import under, choose ••• (More actions) > Markdown import and export, and drop a folder, a .zip or Markdown files onto the window.

Liftmark appears in four places:

• Page ••• menu > Markdown import and export: import under this page, paste Markdown, or export this page and everything under it. On a folder, the same menu imports into or exports that folder.
• Space sidebar > Markdown import: import anywhere in that space.
• Apps > Liftmark: Start here, Import files, Paste Markdown and Your imports.
• The Markdown macro: type /Markdown in the editor.

Import a folder, a .zip or Markdown files

Drop a folder, a .zip or Markdown files onto the drop zone, or use Choose folder, Choose .zip or Choose files. A GitHub "Download ZIP" works as is. From Apps > Liftmark or the space sidebar, first pick the Space and, under Under page, the exact title of the parent page (leave it empty to import under the space home page).

Nothing is created until you click Import. First you see a preview: the number of pages, folders and attachments, the full Page tree, a list of things to check before importing (broken links, missing images) and any files that no page references, which are not imported.

How the page tree is built

• Every directory that contains Markdown becomes part of the tree. A README, index or _index file in a directory becomes that directory's page.
• A directory without one becomes a Confluence folder, or, if you choose Page listing its contents under Folders without a README, a page that lists its children.
• If the .zip has a single top-level folder, it is unwrapped.
• Order follows front matter (sidebar_position, nav_order, weight, order or position), Docusaurus _category_.json files, then numbered names like 02-setup.md.
• Titles come from front matter title (or sidebar_label), then the first # heading if Use the first # heading as the page title is on, then the file name. Tidy file names turns "02-getting_started.md" into "Getting started".
• Front matter tags, labels or keywords become Confluence labels. YAML (---) and TOML (+++) front matter are both read.
• .git, node_modules and __MACOSX are skipped.

Import options

Links, anchors and images

Liftmark creates all the pages first, then writes their content, so links between files point at the new pages. A link like ../guide/setup.md#install lands on the right heading in the new page. Links to a directory point at its page or folder. Links to files that are not in the import stay as text, and the report says why.

Every image used on a page (Markdown ![]() or HTML <img>) and every linked local file (for example a PDF or a YAML sample) is attached to the page that uses it and shown as a native Confluence image or file link. A missing image becomes a visible placeholder and a warning.

Fenced code keeps its language as a Confluence code block. GitHub alerts (> [!NOTE] and friends) become panels, <details> becomes an expand, task lists become Confluence task lists, and tables keep their column alignment.

Paste Markdown

The Paste Markdown tab creates a single page from text you paste. Give it a Page title, or leave it empty to use the first heading, then Preview page and Import.

While it runs

A progress bar shows each item as it is created. Pause stops after the current item; Cancel import stops and keeps what was already created. Keep the window open while the import runs: your files are read in this browser, and Liftmark can't keep a copy of them. If the window closes, your progress is saved.

Results, retry and resume

When the import finishes you see Imported N items, or a table of every item that failed or was skipped with the reason. Choose Download report (CSV) for the full list (one row per page or folder with its source file, status, Confluence title, URL and notes), Retry after fixing a problem, or Open imported pages.

Apps > Liftmark > Your imports lists your imports from the last 90 days, with their status and counts. Choose Resume or Retry, then select the same folder or .zip again; Liftmark continues where it stopped and adopts pages it already created, so nothing is duplicated. Remove deletes an entry from the list (not the pages).

Importing again to update

Import the same files into the same place again and Liftmark updates the pages it created last time instead of making new ones. The result says how many were "updated from an earlier import", and each page gets a new version in its history. If you import into a different parent or rename the source folder, Liftmark treats it as a new import.

The Markdown macro

Type /Markdown while editing a page. The macro opens a side-by-side editor: Markdown on the left, Preview on the right, updated as you type. Tab inserts two spaces, and Cmd+Enter (Ctrl+Enter on Windows) saves. You can also load a .md file into the editor.

Supported: GitHub-flavored Markdown with tables, task lists, alerts, <details> sections, code with syntax highlighting, and Mermaid diagrams. Links to #headings jump within the macro. For images, attach them to the page and write ![alt](file.png). Images from other websites are shown as a link that opens in a new tab and are never loaded inside Confluence.

The macro's Markdown is indexed, so Confluence search finds words inside it. When you export the page to PDF or Word, the macro is included as native headings, tables, task lists and code; Mermaid diagrams are exported as code blocks. The macro also follows Confluence's dark theme.

Export as Markdown

On any page or folder, choose ••• > Markdown import and export > Export as Markdown. Liftmark downloads that page and every page under it as a .zip:

• one Markdown file per page, with index.md for pages that have children,
• front matter with the title, labels and page id,
• images and attachments next to the pages that use them,
• links between pages as relative links, with heading anchors,
• Markdown macros exported as their original Markdown.

Tick Also include attachments that no page shows or links to to include every attachment. If your browser blocks the download, use Save zip to this page to attach the .zip to the page instead. Stop ends an export early and gives you what was read so far.

The .zip imports back with Liftmark into the same tree with working links.

Licensing and trials

Liftmark is paid through Atlassian: $8 a month for up to 10 users, billed per user above that, with a 30-day free trial. If the subscription is not active, a banner says so, Import and Export as Markdown refuse to run, and Markdown macros show their Markdown as plain text until a site admin renews in Apps > Manage apps. Pages you already imported are normal Confluence pages and are not affected.

Permissions and data handling

Liftmark runs on Atlassian's Forge platform and is built for Runs on Atlassian. It sends nothing outside Atlassian: it makes no calls to other servers, fetches no URLs and stores no tokens.

• Your files are read in your browser and sent only to your Confluence site.
• Imports and exports run as you, so Liftmark can only create, update or read what you could by hand. If you can't add pages in a space, each item fails with an explanation and you can choose Retry once you have permission.
• The only data Liftmark stores is your import progress (file paths, titles, page ids and statuses, never file contents) and your preferences. Each person sees only their own imports. Saved progress expires after 90 days.

Liftmark asks Confluence for permission to read and write pages, folders, attachments and labels, and to read spaces and page trees. Each permission is used for importing or exporting.

Limits and known gaps

• Up to 5,000 files and 300 MB per import. For bigger repositories, import one subfolder at a time.
• Export stops at 5,000 pages.
• A single Markdown macro holds up to 100,000 characters. For longer documents, use Import, which creates real pages.
• Files come from your computer. Liftmark does not import from a Git URL.
• The browser window must stay open while an import runs. A docs repository of a few hundred pages takes a few minutes.
• Raw HTML tables in Markdown are imported as plain text, with a warning.
• On export, Confluence macros that have no Markdown equivalent become an HTML comment naming the macro, so you can see where they were. Only pages and folders are exported, not whiteboards or databases.
• If your site rejects the Markdown macro on an imported page, Mermaid diagrams on that page are kept as code blocks, and the report says so.

FAQ

Will my folder structure be flattened? No. Folders become a page tree in your order, with README or index files as section pages. You see the whole tree before anything is created.

Do relative links and images survive? Yes. Links between files, including links to a heading in another file, point at the new pages. Images and linked files are attached to the page that uses them. Anything that can't be linked is listed in the preview and in the report.

What happens if one file fails? That file is marked failed with a reason and the rest of the import continues. Fix the problem and choose Retry. Liftmark also retries automatically when Confluence asks it to slow down.

I ran the import twice. Do I get duplicate pages? No. Importing the same files into the same place updates the pages from last time. Use If a page with the same title exists to decide what happens with pages Liftmark did not create.

Can I stop an import that is taking too long? Yes: Pause or Cancel import at any time, and Resume later from Your imports.

Do anchor links to headings work? Yes, in imported pages and in the macro.

Is code highlighted? In the macro, yes. On imported pages, fenced code becomes a Confluence code block in the same language.

Do I need to give Liftmark a GitHub or Bitbucket token? No. Liftmark never fetches URLs, so there are no tokens to store. Download the repository as a .zip and import that.

Where do I find it after installing? The page ••• menu (Markdown import and export), the space sidebar (Markdown import), and Apps > Liftmark with a Start here guide.

Does Confluence's own Markdown paste do the same thing? Pasting Markdown into the editor converts basic formatting on one page. Liftmark imports whole folders with images and links, keeps Markdown as Markdown in the macro, renders Mermaid, and exports page trees back to Markdown.

Uninstalling and your data

Export any page trees you want as Markdown first if you plan to leave Confluence. Imported pages are normal Confluence pages and stay after you uninstall. Markdown macros stop rendering once the app is removed. When the app is uninstalled, Atlassian deletes Liftmark's stored import history for your site.

Support

Open a request in the Great Work support portal (linked from the Marketplace listing) or email hello@greatwork.company. When something goes wrong with an import, attach the report from Download report (CSV). We answer within one business day (US Central time). Security reports: within 4 hours.