Moving documentation in

Bringing documentation from Notion, Obsidian, GitBook, Outline, MkDocs, Docusaurus or any folder of Markdown or HTML into a knowledge base space, in its own tree, with its links and images working.

Documentation kept in another tool usually leaves it as a folder of files: Markdown or HTML pages with their images. Alba Ticket reads such a folder, zipped, into one space of the knowledge base: the pages in the tree the tool showed them in, Markdown kept as it was written, HTML converted to Markdown, and every link between pages and every image pointed at the page or file it became here.

Exporting your documentation

Any ZIP of a folder of .md, .mdx or .html files and their images will do. From the tools this was built with:

  • Notion: the page's ••• menu, Export, Markdown & CSV (or HTML), with subpages and files. Notion's ZIP can be imported as it is.
  • Obsidian: zip the vault's folder.
  • GitBook: sync the space with a Git repository, or export it, and zip the folder that holds SUMMARY.md.
  • Outline: a collection's Export, Markdown.
  • MkDocs and Docusaurus: zip the project's folder, with mkdocs.yml or sidebars.js.
  • A Git repository of Markdown: its Download ZIP is enough; the folder it is wrapped in is looked through.

Analysing the ZIP

Under Administration, Documentation import, Upload a ZIP. The ZIP goes straight from your browser to the workspace's storage and is read as soon as it is there. The analysis writes nothing. It says:

  • which tool the folder came from (GitBook, MkDocs, Docusaurus, Notion, Obsidian, or a plain folder of Markdown or HTML);
  • the tree it will make, each page with the file it comes from;
  • how many pages, how many of them are HTML to convert, and how many files;
  • anything it noticed: a page the navigation leaves out, a navigation entry for a file the ZIP does not hold, a Docusaurus sidebar built in code;
  • MDX components and imports, which are kept as their source;
  • every link that leads to nothing in the ZIP;
  • what is left out and why: code and configuration files (.js, .yml, stylesheets), pages outside the documentation folder of an MkDocs or Docusaurus project, and tools' own folders (.git, .obsidian).

How the tree is made

Where the tool has its own navigation, it decides the tree and the order: GitBook's SUMMARY.md (a ## heading in it is a section), MkDocs's nav in mkdocs.yml, and Docusaurus's sidebars (read as data, never run; an autogenerated part is read from its folder, with _category_.json). A page the navigation leaves out is placed at the top level.

Anywhere else the folders make the tree. A folder's page is its index.md or README.md, or a file beside it with the folder's name, as Notion writes a page with subpages; a folder with neither is a section with no page of its own. Pages are ordered by sidebar_position, nav_order, weight or order in their front matter, then by a number at the start of the file name, then by name. Notion's subpages follow the order their page links to them.

A page's title is the navigation's, else the front matter's title, else its first heading, else the file name without Notion's page id or a leading number. An Obsidian note's title is its file name.

Importing

On the analysis's page, choose where the pages go, Into: a new workspace space (give it a key and a name; the analysis suggests them), a space that exists, or a project's space, which is made with the project's key if the project has none. Tick Dry run to try it and roll it back, and start the import. It runs in these steps:

  • Space: the space is found or made.
  • Files: every file that is not a page or code, images, PDFs and a Notion database's CSV alike, becomes a file of the space, in the workspace's storage.
  • Pages: the tree, then each page's body. Markdown stays as it was written, its front matter kept with the page's import record rather than shown. Relative links and images, reference definitions, src and href in HTML inside the Markdown, and Obsidian's [[wikilinks]], [[Note|words]], [[Note#Heading]] and embeds (![[image.png]]) are pointed at the pages and files here; a link to a heading goes to that heading. Nothing inside code is changed. MDX's import and export lines and its components are kept as fenced blocks of their source. An HTML page is converted to Markdown by the same converter that opens Confluence pages for editing. The first page at the top becomes the space's home page if it has none.
  • Missing: what an earlier import brought that this ZIP no longer holds (see below).
  • Links: what every page links to, so links between pages and ticket keys work straight away, and the space is queued for search.

Importing a newer version

Import a newer ZIP of the same documentation into the same space and only what changed changes: a page whose text changed gets a new version, one that did not is left alone, a page moved in the source moves here, a file whose bytes changed gets a new version. A page somebody has edited here since it was imported is left as they made it, and the run says so.

Pages and files the newer ZIP no longer holds are listed on the run's page. Tick Archive pages an earlier import brought that this ZIP no longer holds to archive them as well; nothing is deleted, so an archived page keeps its history and comes back if a later ZIP has it again.