Skip to content
Docs

Import and export

You can bring existing documentation into an Orbit Folio space and take it out again. This page is for people who write in a space. It covers Markdown imports, Confluence HTML imports, exports and printing.

Import a Markdown zip

Section titled “Import a Markdown zip”

Folio imports a .zip written by Obsidian, Outline or GitBook, or by a Folio export. Anyone who can write in the space can import.

  1. Open the space tools and choose Import.

  2. Choose the zip file and the page it should go under, or leave the space overview.

  3. Run the dry run. Folio shows the tree of pages it would create, the number of files, and the files it would skip with the reason. Nothing is written.

  4. Confirm. Folio creates everything in one step. If something fails, nothing is created.

How the folders become pages

Section titled “How the folders become pages”
  • A single top-level folder is removed.
  • A folder with Markdown inside becomes a page. Its text is Title.md next to the folder, or else README.md or index.md in it. A folder with neither becomes an empty page.
  • Hidden folders such as .obsidian and .git, the __MACOSX folder and the GitBook SUMMARY.md are skipped.
  • The title is the title in the front matter, or else the file name. A first # H1 heading that repeats the title is removed.
  • tags in the front matter, as a list or separated by commas, become labels. Team/Ops becomes team-ops.
Section titled “Links and files”
  • [[Note]], [[Folder/Note|alias]], [[Note#Heading]] and Markdown links to .md files point to the new pages. Folio writes [[Title]] when the title is unique in the space, and a permanent link /folio/p/<id> otherwise.
  • ![[image.png]] and ![](path) point to the uploaded files of the first page that refers to them.
  • Code is never changed, and external links stay as they are.
  • Files are checked like any upload. The type is read from the extension and the first bytes. The limits are 25 MB per file, 100 files per page and the space quota.
  • A file that no page refers to is not imported.

Limits

Section titled “Limits”
Limit Value
Zip file 100 MB
Pages 2,000
Files 1,000
Unpacked size 1 GB
Imports at once One per person

Each created page has the version note Imported from <zip>. The activity log gets one entry for the whole import.

Import a Confluence space export

Section titled “Import a Confluence space export”

The same Import dialog recognizes the HTML export of a Confluence space. In Confluence, choose Space settings, Export space, HTML. The export has index.html at its root, pages named like Title_<id>.html, and an attachments folder.

Folio builds the page tree from the Available Pages list in index.html, or from the breadcrumbs of each page. The space name is removed from titles, so Engineering : Deploy becomes Deploy.

Macros become Folio markup:

Confluence Folio
Info, tip, note, warning Callouts
Code, no-format Code block, with the language of the macro
Expand Collapsible section
Table of contents [TOC]
Panel > [!NOTE] quote panel
Task list Check-list
Status {status:...} label, in tables too
Date {date:...}
Mention @Name

Page tree, page metadata and recently updated macros are skipped.

Links between exported pages become [[Title]] links. A link to a page that is not in the export becomes plain words. Links outside http(s) and mailto stay as text.

Attachments belong to their page and keep their Confluence names. The images, styles, .css and .js files of the export are skipped silently. Some content is skipped, and the list gives the reason. This covers other files, a page without #main-content, an HTML file over 8 MB and a page over 1 MB after conversion. The dry run, the limits, the activity log and the permissions are the same as for Markdown.

Export pages and spaces

Section titled “Export pages and spaces”

Export a page, a page with its subtree, or a whole space as a Markdown zip with its attachments. Readers can export pages they can see. Choose Export… in the page menu, or Export in the space tools.

Folio first shows what the archive will contain: pages, files and size. If no archive can be built, it says why.

In the zip How
Pages Title.md, with a folder Title/ for child pages
Files In _attachments/
Metadata YAML at the top of each file: title, folio_id, folio_space, version, created, updated, and labels as tags
Links Attachments and permanent links to exported pages become relative paths. [[Title]] points to the renamed file.

The folder opens in Obsidian, Outline and GitBook. A Folio export imports back into Folio without losing titles, labels, links or attachments.

File names are safe on Windows, macOS and Obsidian, and unique inside a folder without regard to case. The archive holds only the pages the reader can see. A project administrator gets all pages. An archive has at most 5,000 pages and 1 GB, and a person can run one export at a time.

Section titled “Print to PDF”

Choose Print or save as PDF in the page menu, or press Ctrl+P. The printout hides everything but the page: the Orbit shell, the tree, buttons, discussion and live widgets. Code prints dark on white, and tables and blocks are not split across pages.

Section titled “Related”