Support and setup guide

Need help? Email support@definitivepages.com. We reply within one business day.

What you can import

• Markdown: any folder of .md files, plus the conventions of GitHub and Azure DevOps wikis, MkDocs, Docusaurus, Obsidian vaults and Notion exports.
• AsciiDoc: .adoc files, including Antora sites. include:: files are read from what you choose (with tag= and lines=). Files named _something.adoc and files in partials/ or includes/ are includes, not pages. In an Antora site, each module's pages/ folder becomes a branch and nav.adoc sets the order.
• HTML folders: a built documentation site or an exported intranet. Only each page's content area is imported, without the site's header, menus and footer. For Sphinx, choose the _build/html folder; pages keep Sphinx's order. HTML is imported only when the folder has no Markdown or AsciiDoc.
• Jupyter notebooks (.ipynb): each notebook becomes a page. Markdown cells convert like Markdown, code keeps its language, charts become images, pandas tables become real tables, and printed output and errors become code blocks. Interactive widgets are left out with a note. Notebooks aren't run, so save them with their outputs; re-running one without changes doesn't count as a change on re-import.
• reStructuredText: build the HTML with Sphinx (make html) and import that.

Import a folder

1. Open the importer. Choose Apps → Definitive Pages, then pick a space and a parent page. Or, on any page, choose ••• → Apps → Definitive Pages: the import goes under that page.
2. Add your files. Drop a folder or a .zip file, or use Choose a folder or Choose a .zip file.
3. Check the preview. The tree shows every page that will be created, and the badge names the kind of source it found (for example Obsidian vault or MkDocs project). Before you import lists links or images that couldn't be matched, skipped files, and files no page links to.
4. Import. Keep the page open until the progress bar finishes. The report lists every page with its result; Copy report gives you a CSV, and Save report to the top page attaches it there.

Files are read in your browser and sent only to your Confluence site, as you. Nothing passes through other servers.

Update an import

Open the top page of the import and choose ••• → Apps → Definitive Pages. Or use Update an earlier import on the app's start page, or select Source: … on any imported page and choose Update the import…. Then choose the updated folder or .zip.

• New file: a new page, placed in order among its siblings.
• Changed file: its page is updated (one new version).
• Unchanged file: nothing happens. No new version, no notification.
• Renamed or moved file (same content): the same page is renamed or moved, keeping its history and comments.
• Removed file: its page is kept (the default), archived, or moved to the trash, as you choose. A page that still has other child pages is never archived or trashed.

Pages changed in Confluence since the last import (edited, deleted or archived) are skipped and marked in the preview. Choose Overwrite them from the files to replace those edits; deleted pages then come back under their parent.

Migrating from another wiki? Import early and keep re-importing while people still edit the old one. Only changed files are rewritten, so nobody has to freeze the old wiki before cutover day.

If an import is interrupted (tab closed, network lost), run it again on the same files. It finishes the pages it started and doesn't create duplicates.

The source line on imported pages

Every imported page shows the file it came from next to the author, for example Source: install.md. Select it to see the file's path, the import it belongs to and when the import last ran, and whether the page is in sync or was edited here in Confluence since. Update the import… opens the importer for that import without leaving the page. When a file is removed and its page kept, the page stops showing a source line.

How files become pages

• Folders become parent pages. index.md, README.md, _index.md or Home.md becomes the folder's own page (the list is configurable), as does X.md next to a folder X/ (Notion, Azure DevOps) and an Obsidian folder note X/X.md. A folder without one gets a page listing its children.
• Titles come from the front-matter title, then the first heading (removed from the body so it isn't shown twice), then the file name. 01-getting-started.md becomes "Getting started". Titles must be unique in a space, so a taken title gets its parent's name in brackets, and the report says so.
• Order: front-matter sidebar_position, nav_order, weight or order, Azure DevOps .order, Docusaurus _category_.json and MkDocs nav come first, then names.
• Labels come from front-matter tags, tag or labels.

What converts to what

• Headings, lists, tables, bold, italic, strikethrough and inline code convert as they are. Task lists become Confluence task lists.
• Code blocks keep their language; MkDocs title="…" is shown above the block. Mermaid blocks stay as code.
• Callouts become panels: GitHub and Obsidian > [!NOTE], MkDocs !!! note, Docusaurus :::tip and Notion <aside>.
• <details> becomes an expand, and [[_TOC_]] or [TOC] a table of contents.
• Images (relative, root-relative or base64) become attachments shown inline; remote images are shown from their URL.
• Links to other .md files, folders and #headings point to the imported pages and their headings. Links to other files (PDF and so on) become attachments.
• Obsidian [[Note]], [[Note|alias]], [[Note#Heading]], ![[image.png]] and aliases become page links, anchors and images. Footnotes become numbered notes at the end of the page.
• Front matter sets the title and labels and isn't shown on the page. Obsidian %%comments%%, MDX import lines and other HTML tags are removed (their text stays).

Options

Page title source, removing the heading that became the title, tidy file names, labels from tags, importing only the docs folder (MkDocs and Docusaurus), line breaks, folder-page file names, skip patterns such as drafts/**, and the top page's title. Updates reuse the options of the first import; changing an option rewrites every page once.

Troubleshooting

"Link not resolved" or "Image not found"

The target isn't in the files you chose, or its name differs in case or spelling. The page is still created, with the link shown as plain text.

A page shows as skipped

It was changed in Confluence after the last import. Choose Overwrite them from the files to replace it.

Importing is turned off

The app's license for your site isn't active. You can still preview a folder. A site admin can check the license under Apps → Manage apps.

Data and security

Definitive Pages runs entirely on Atlassian's Forge platform. Your files are read in your browser and written to your own Confluence site as you; nothing is sent to us or anyone else. See the privacy policy.