Description

KIRA's documentation system integrates with docu-notion-kira, a forked version of docu-notion tailored for Kira Network.

Docu-notion allows the use of Notion as the primary editing platform to produce content suitable for static site generators; Docusaurus in this case. This combination meets several challenging requirements, such as automatique deployment, editing workflow features, localization support via Crowdin, and capabilities for both online and offline distribution. Future plans include adding versioning capabilities.

How It Works ?

Docu-notion fetches content from a provided Notion root page and produce a structured folder of markdown-base files of its content. The root page has two main components:

1. The Database (Optional) - This is where the documentation pages are stored. They include content and are equipped with workflow properties to facilitate a Kanban-style management process where pages can have metadata that can be leveraged and are published according to their ‘status’.
2. The Outline Page (Mandatory) - This is a central Notion page that organizes content hierarchically. It serves as the foundation of the documentation structure. The arrangement of sub-pages within the Outline is directly reflected in the final documentation site and its sidebar navigation. These sub-pages should link back to the relevant documents housed in the database.

Page Structure in the Outline

Blocks listed under the Outline page can be of the following types:

• A page level without Index : A page containing child pages or links to database pages, but doesn't have any content.

• A page level with Index : A page containing child pages and/or links to database pages, and has content. An index.md will be created and all child pages and link to database page will be stripped out from it.

• A link to a database page

• Or a standard page with content

  The use of the database is optional because pages with content can be directly included in the Outline. However, these pages won't have access to the advanced workflow features provided by the database properties. A level page (a.k.a Category in Docusaurus) function as subsections of the documentation. They are transformed into dropdown menus in the sidebar of the documentation site. If they hold content it will be parsed into an index.md.

Links

Docu-notion automatically identifies and removes blocks that are either child pages or links to pages located at the root level of the page. If you need to include such blocks within your content, they must be embedded within another block type, like a table or a column, or they should be accompanied by some text within the same block to trick this logic.

Custom Pages

Docusaurus automatically generates custom pages from the src/pages directory, creating corresponding slugs and links. You can create any page within the root page in Notion, for instance naming it "src/page", and manually move these pages into the Docusaurus src/pages folder as needed. This approach is simpler and easily managed using github workflow.

Note on Conflicts: Pages within src/pages are prioritized by Docusaurus and can lead to conflicts with pages that have matching slugs elsewhere in the project. E.g. If both an index.md or a page with "/" slug in the main documentation and an "index.js" in src/pages exist, Docusaurus will prioritize the content in src/pages, potentially overlooking the index.md.

Custom parsing (Plugins)

Custom parsing logic can be created using plugins. See the plugin readme.

Callouts ➜ Admonitions

To map Notion callouts to Docusaurus admonitions, ensure the icon is for the type you want.

• ℹ️ ➜ note
• 📝➜ note
• 💡➜ tip
• ❗➜ info
• ⚠️➜ caution
• 🔥➜ danger

The default admonition type, if no matching icon is found, is "note".

Setup: Docu-notion-kira + docusaurus

Host specs:

Ubuntu 20.04

Software specs:

• NodeJS [v21.4.0]
• npm [v10.2.4]
• yarn [v1.22.21]

NodeJS installation

1. Create a Temporary Directory:

mkdir -p ~/tmp && cd ~/tmp 

2. Download NodeJS:

wget https://nodejs.org/dist/v21.4.0/node-v21.4.0-linux-x64.tar.xz

3. Unpack NodeJS and Set Environment Variables:

   • Use one of the following methods:

   • Method A (Persistent Environment Variables):

     sudo mkdir -p /usr/local/lib/nodejs
     sudo tar -xJvf node-v21.4.0-linux-x64.tar.xz -C /usr/local/lib/nodejs
     echo 'export NODEJS_HOME=/usr/local/lib/nodejs/node-v21.4.0-linux-x64' | sudo tee -a /etc/profile
     echo 'export PATH=$NODEJS_HOME/bin:$PATH' | sudo tee -a /etc/profile
     source /etc/profile

   • Method B (Temporary Environment Variables):

     sudo mkdir -p /usr/local/lib/nodejs
     sudo tar -xJvf node-v21.4.0-linux-x64.tar.xz -C /usr/local/lib/nodejs
     echo 'export NODEJS_HOME=/usr/local/lib/nodejs/node-v21.4.0-linux-x64' | sudo tee -a /etc/profile
     echo 'export PATH=$NODEJS_HOME/bin:$PATH' | sudo tee -a /etc/profile
     source /etc/profile

4. Install yarn:

npm install --global yarn

5. Check Installed Versions:

node -v
npm -v
yarn -v

Clone and Prepare Repository for Docusaurus

1. Clone the Repository:

cd ~/tmp
git clone https://github.com/kmlbgn/docs.kira.network.git

2. Set Notion API Token and Root Page:

• Replace *** with your Notion token and root page ID.
• Set Environment Variables:

  export DOCU_NOTION_SAMPLE_ROOT_PAGE=[***]
  export DOCU_NOTION_INTEGRATION_TOKEN=[***]

• Go to the root page and add docu-notion-kira integration. This page should have, as direct children, "Outline" (required) and "Database" (optional) pages. Follow these instructions. Source: Notion integration

3. Install Dependencies:

npm install

4. Parse Pages with docu-notion:

npx docu-notion-kira -n $DOCU_NOTION_INTEGRATION_TOKEN -r $DOCU_NOTION_SAMPLE_ROOT_PAGE

Starting Docusaurus Server

1. Navigate to the Project Directory:
2. Start the Docusaurus Server:

yarn start

• Source Docusaurus Intallation Guide

Docu-notion Command line

Usage: docu-notion-kira -n -r [options]

Options: