Migrating from Gitbook

This page describes how to manually migrate content from Gitbook to this Cloudcannon wiki site. This is aimed towards developers migrating the content via Git sync and editing raw markdown text.

Note - All Gitbook Documentation has now been migrated

Each Gitbook space must be migrated separately. There are two main steps to migrate content for a Gitbook space:

Sync the Gitbook space with the FP backup repo. This enables access to the raw markdown content. [Done]
Migrate the Gitbook markdown content to this wiki format. [Done]

#Sync Gitbook space to temporary FP Github repo [Done]

Update: All Gitbook spaces have been synced to the Github repo, currently here:

https://github.com/ForPurposeNZ/gitbooks-sync-test

Instructions

Go to the Gitbook space to migrate, and click Configure in top right (look for Github logo).
In the pop up, select Github Sync button and click Next Step
You might need to Authenticate with your Github account. Click Connect with Github and the Authorise with Github on the new page.
Select Github account: ForPurposeNZ
Select repository, use: gitbooks-sync-test
Select branch: main
Under Monorepo -> Project Directory, pick (type in) a new project directory folder. This is important - it creates a new subfolder in the existing repo to add the docs for the space. Just choose a folder name that matches that Gitbook space, for example reo-maori-dev-docs
Initial sync - select Gitbook to Github. This is important. Don't select 'Github to Gitbook' or it wipes the Gitbook space.
Hit "Sync"

Once sync is complete, you can click View Repo and you should see your new folder containing the documentation in the FP Github repo:

https://github.com/ForPurposeNZ/gitbooks-sync-test

If not done, you can checkout this repo.

Migrate Markdown to Cloudcannon Wiki

Note - the Gitbook documentation was migrated using a script (found in the _scripts folder). This lists the steps to do it manually.

Now the markdown content in the backup Gitbook repository can be migrated to this Wiki repository. It is easier to do this by editing the raw markdown files.

Use Git to check out this documentation wiki repository: https://github.com/ForPurposeNZ/fp-documentation-site
Use Git to check out the temporary Gitbook sync repo: https://github.com/ForPurposeNZ/gitbooks-sync-test
In the wiki repo, create a new folder under the src/docs folder. Give it the spaces name (ie, reo-maori)
Copy all the markdown files and subfolders from Gitbook folder to the new wiki folder. Do not copy the assets in .gitbook/assets (next steps).
Create a new folder for assets in the wiki in src/assets/images. Give the folder the same name as your docs folder.
Copy the assets (images etc) from .gitbook/assets to this new folder.
Add frontmatter to markdown files. The Alto wiki requires a frontmatter section to correctly display the pages.
```
---
title: {title}
layout: layouts/page.html
eleventyNavigation:
 key: {sidebar key aka default title}
 order: {optional - sidebar order}
 title: {optional - override sidebar key value}
 parent: {optional - set to parent key to nest menu item}
tags: {spaces name - keep same across all docs}
date: Last Modified
draft: false
_schema: default
---
```
The most important frontmatter field is the tags: field. Set this to your spaces name, for example "Generation Zero". This should be the same for all documents in the same space. This is shown in the sidebar as the document group heading, and is used to link all the documents together.

Move the first #heading from the top of the markdown and paste it in the title: field (this is shown as the document title).

The eleventyNavigation: fields control how the document appears in the sidebar:

The simple option is to just set the key: field to the document title. This will show as a menu item on the left.

Optionally set the order: field to a number to control the order of the item in the sidebar.

If you wish to nest a menu item under another menu item, set the parent: field to the key of the parent page.

You can optionally set the title: field to override the key: as the text shown in the sidebar. This allows you to use a simple key:, for example key:cat and title:A long sidebar menu item for cats.

For more information see the Eleventy Navigation documentation.

Leave date: Last Modified - this is used to automatically show the last modified date in the footer.
Tidy the welcome page. It is recommended to merge the Gitbook README.md (intro) and SUMMARY.md (contents) files into a single index.md file.
Correct the internal links in the markdown documents. The Alto wiki generates files slightly differently.
Firstly there is no markdown extension in the generated documents, so remove all .md from links. For example a Gitbook link [link name](folder/file.md) should be changed to [link name](folder/file)
For anchor links to the same page, it was necessary to remove the page name from the start of the link, for example [#top-white-section](section-info.md#top-white-section "mention") needed to be changed to [#top-white-section](#top-white-section "mention")
If there are relative links to sibling documents they should be checked. It might be necessary to add a relative path to the links ../document
Correct the asset links in the markdown documents.
At the minimum update the links with the new image locations - replace all occurrences of ../.gitbook/assets with /assets/images/<spaces-folder>
Additionally, if possible, convert Gitbook <figure> tags to either a wiki image shortcode or an figure snippet. This is because although the Gitbook figure tags work on the web page, they cannot be edited in the Cloudcannon editor.
To convert a figure tag to a wiki image shortcode, change the Gitbook figure tag:
<figure><img src="../.gitbook/assets/file.ext" alt=""><figcaption></figcaption></figure>
to:
![](/assets/images/spaces-folder/file.ext)
Alt text can be placed in the [] or a caption copied below as normal text.
Alternatively to convert to a figure snippet, change the text to:

{ % figure, "<path/image.ext>" "<image caption>" "<image alt>" "" "" "" "" "" "" "" "" "" % }

Notes:
a. remove the spaces between { and %
b. the empty quotes are for additional figure snippet fields - they can be explored by looking at the Figure snippet in the editor.
Some Gitbook html tags render fine on the web page but cannot be changed in the Cloudcannon editor. This includes <mark> tags. The easiest option in the short term is to delete the tags and replace with **bold** markdown.