Nebula Genesis

nebula-genesis is part of the Nebula suite.

Nebula connects Notion API (as headless CMS) and Astro (a SSG, static site generator) to automatically create static websites.

Nebula Genesis acts prior to the website generation :

It's a npm module that query, download, cache and (optionnaly) parse Notion databases' pages to Markdown.

Table of contents

• Nebula Genesis
  • Table of contents
  • How to use ?
    • 1. Install
    • 2. Querying
  • Where is data downloaded ?
    • Download location
      • 1. Cache folder
      • 2. Astro collection folder
    • Folder structure
  • Arguments
    • Required arguments
      • NOTION_TOKEN
      • DATABASE_ID
    • Optional arguments
      • FILTERS
      • SITE_FOLDER_PATH
      • CACHE_FOLDER_NAME
      • ON_OR_AFTER
      • REINIT_CACHE
      • OUTPUT_FORMAT
      • ASTRO_COLLECTION_NAME
      • CONTAINER_WIDTH
  • Notion's features support
    • Blocks types' support
    • Property types' support
  • Development
    • 1. Clone repo on your computer
    • 2. Install dependencies
    • 3. Build dev script
    • 4. Install in test site
  • Publishing
    • 1. Build prod script
    • 2. Publish on npm

How to use ?

1. Install

Install nebula-genesis as a dev dependency in your website project.

npm i -D nebula-genesis

2. Querying

Query databases and pages according to your needs.

It is a normal use case to run 2 or more times nebula-genesis, with different CACHE_FOLDER_NAME, to fetch content from mutiple databases or with differents filters.

This will download content in a cache folder, as detailed in Download folder section.

Required and optional arguments are detailed in the Arguments section.

npx genesis [...args]

Where is data downloaded ?

Download location

Depending on [arguments], content will be stored at different locations.

1. Cache folder

By default, content is stored in a cache folder, located at :

<SITE_FOLDER_PATH>/cache/<CACHE_FOLDER_NAME>

2. Astro collection folder

If <ASTRO_COLLECTION_NAME> is set, pages are downloaded and parsed to the following location :

<SITE_FOLDER_PATH>/src/data<ASTRO_COLLECTION_NAME>

Files (like images) from pages' blocks are directly stored inside <SITE_FOLDER_PATH>/static folder.

Don't forget to ignore cached files from ./static.

Folder structure

Inside CACHE_FOLDER_NAME folder, content is stored on the following structure :

• cache.json, which contains nebula-genesis metadata, currently only the LAST_RUN date,
• pages.json, with the result of the main database query (PageObjectResponse[]),
• pages folder,
  • <PAGE_ID>,
    • page.json, with the result of the pages query (BlockObjectResponse[]).

Arguments

Required arguments

NOTION_TOKEN

NOTION_TOKEN is your Notion integration key.

You must connect relevant databases to your integration in order to query them.

DATABASE_ID

DATABASE_ID is the ID of the database you want to query.

Optional arguments

FILTERS

FILTERS are JSON-formatted filters to apply to the database query.

See Filter database entries (developers.notion.com) for filters reference.

SITE_FOLDER_PATH

Default value : "." (website project root).

SITE_FOLDER_PATH is the path to the folder where you want to store the generated files.

CACHE_FOLDER_NAME

CACHE_FOLDER_NAME is the name of the folder where data is cached.

See Download location section for cache folder path.

ON_OR_AFTER

ON_OR_AFTER is the date from which you want to query pages.

REINIT_CACHE

REINIT_CACHE can be set with whatever value to ignore cache.

OUTPUT_FORMAT

OUTPUT_FORMAT can either be 'md' (default) or "json".

ASTRO_COLLECTION_NAME

ASTRO_COLLECTION_NAME will write MD files in an Astro-shaped folder, structured as /pages/<name>/<page-id>.md.

Collections can then be set in website codesource, using src/content.config.ts

CONTAINER_WIDTH

Default : 600

Target size for downloaded image, equal to content container max width.

Notion's features support

Blocks types' support

• Paragraph
• Heading 1
• Heading 2
• Heading 3
• Bulleted list item
• Numbered list item
• Quote
• Callout
• Image

Property types' support

• rich_text
• title
• number
• date
• checkbox
• select
• multi_select

Development

You can extend nebula-genesis's features by locally developing its codebase, following these steps :

1. Clone repo on your computer

git clone github.com/abstract-core/nebula-genesis.git

We find it esaier to clone sources in the same folder as the Astro test site project you will use (ex: in dev/ you'll find nebula-genesis/ and my-astro-project/).

2. Install dependencies

npm i

3. Build dev script

npm run dev

In order to transpile (from TS to JS), and to bundle files in a single script, we use npx esbuild to output a build/index.js.

This script has the watch flag turned on.

4. Install in test site

Taking the 1. Clone repo on your computer example folder structure, you should execute the following script to install dev module in your test site :

npm i ../nebula-genesis

Publishing

1. Build prod script

npm run build

2. Publish on npm

npm publish