API

💡

Our API uses the term "parent" page to indicate what Notion calls a "database" page , ie. a page that contains a list of pages that share the same properties. We call any page that is not a parent page is an "entry" page, ie. a page that contains content blocks (text, images, lists, etc). If an entry page has a parent (ie. is in a Notion "database") and is being referred to in relation to its parent, we call them a "child" page.

getStandalonePage

Get an “entry” page data by id.

Props

notionId

type: string (required)

A public Notion page ID.

The last path segment of an entry page contains a slugified title and the page ID. For instance, in notion.so/an-data/Plants-1cf6f82effc24ad4aea5a50f88198a7b , the ID is 1cf6f82effc24ad4aea5a50f88198a7b . You can pass either the uuid (with the - ) or id format.

JavaScript

import { getStandalonePage } from "astronotion/api";

const pageData = await getStandalonePage("1cf6f82e-ffc2-4ad4-aea5-a50f88198a7b");

Returned

type: AnEntryPageData | undefined

“Entry” page data object.

If the page is not available for public access or is not the right page type, the method returns undefined with additional info in server log, if available.

TypeScript

type AnEntryPageData = {
  title: string;
  icon?: string;
  cover?: {
    url: string;
    position?: number;
  };
  description?: Decoration[];
  id: string;
  taxonomies: string[];
  created: number;
  updated: number;
  contents: AnContentBlock[];
};

Example

JavaScript

{
  id: '1cf6f82e-ffc2-4ad4-aea5-a50f88198a7b',
  title: 'Plants',
  icon: '🌱',
  cover: {
    url: 'https://s3.us-west-2.amazonaws.com/secure.notion-static.com/be4b2294-2834-4cef-a8db-414c477a9218/igor-son-FV_PxCqgtwc-unsplash.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAT73L2G45EIPT3X45%2F20220521%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20220521T081717Z&X-Amz-Expires=86400&X-Amz-Signature=89c2341516e849843c5e49d8afa4df67a189d6a50e57c8fc84797be2236f5bd6&X-Amz-SignedHeaders=host&x-id=GetObject',
    position: 0.2353
  },
  contents: [
    // content block objects
    {
      id: '....',
      type: 'text',
      properties: [],
      // ... etc
    },
  ],
  taxonomies: [],
  created: 1650250500000,
  updated: 1652729700000
}

getParentPage

Get a “parent” page data by id.

Props

notionId

type: string (required)

A public Notion page ID.

The last path segment of a parent page only contains the page ID, for instance notion.so/an-data/2ba80ec3d84d46479f23ec15ba5e39b0 . You can pass either the uuid (with the - ) or id format.

JavaScript

import { getParentPage } from "astronotion/api";

const pageData = await getParentPage("2ba80ec3-d84d-4647-9f23-ec15ba5e39b0");

Returned

type: AnParentPageData | undefined

“Parent” page data object.

If the page is not available for public access or is not the right page type, the method returns undefined with additional info in server log, if available.

TypeScript

type AnParentPageData = {
  title: string;
  icon?: string;
  cover?: {
    url: string;
    position?: number;
  };
  description?: Decoration[];
  childPages: {
    id: string;
    taxonomies: string[];
    created: number;
    updated: number;
  }[];
};

Example

JavaScript

{
  id: '2ba80ec3-d84d-4647-9f23-ec15ba5e39b0',
  title: 'Journal',
  icon: '📓',
  description: [
    [ 'Eu proident non eiusmod proident aliqua elit qui ' ],
    [ 'pariatur', [['c']],
    [ ' eiusmod anim magna velit amet.' ]
  ],
  childPages: [
    // child pages data
    {
      id: '10c7053a-5cb5-4746-9336-09fb4eac55a8',
      title: 'Just another day',
      cover: {
        url: 'https://images.unsplash.com/photo-1520520731457-9283dd14aa66?ixlib=rb-1.2.1&q=85&fm=jpg&crop=entropy&cs=srgb',
        position: 0.5984,
      },
      taxonomies: [],
      created: 1650189589678,
      updated: 1651342800000
    },
    // ... etc
  ],
  taxonomies: [],
  created: 1650250500000,
  updated: 1652729700000
}

getChildPagesStaticPaths

Programmatically generate Astro static paths for the “child” pages of a specified “parent” page.

Props

parentConfig

type: { parentId: string; childPages: AnParentPageData["childPages"] } (required)

An object that contains the “parent” page ID and the childPages property returned by getParentPage .

💡

The next minor release will enable passing only the parent page ID (no need to run getParentPage first), while remaining backward compatible with the current prop.

JavaScript

import { getParentPage, getChildPagesStaticPaths } from "astronotion/api";

// see: https://docs.astro.build/en/reference/api-reference/#getstaticpaths
export async function getStaticPaths() {
  const EXAMPLE_NOTION_ID = "2ba80ec3-d84d-4647-9f23-ec15ba5e39b0";

  const parent = await getParentPage(EXAMPLE_NOTION_ID);

  return getChildPagesStaticPaths({
    parentId: EXAMPLE_NOTION_ID,
    childPages: parent.childPages,
  });
}

Returned

type: AnChildAstroStaticPath[]

Astro path object with a params.fullSlug property and props containing page type and data.

TypeScript

type AnChildAstroStaticPath = {
  params: { fullSlug: string };
  props: AnEntryPage;
}

Example

JavaScript

[
  {
    params: { fullSlug: '1cf6f82e-ffc2-4ad4-aea5-a50f88198a7b' },
    props: {
      pageType: 'NOTION_ENTRY',
      pageData: {
        id: '1cf6f82e-ffc2-4ad4-aea5-a50f88198a7b',
        title: 'Plants',
        icon: '🌱',
        cover: {
          url: 'https://s3.us-west-2.amazonaws.com/secure.notion-static.com/be4b2294-2834-4cef-a8db-414c477a9218/igor-son-FV_PxCqgtwc-unsplash.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAT73L2G45EIPT3X45%2F20220521%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20220521T101538Z&X-Amz-Expires=86400&X-Amz-Signature=1493c6511708cc5a016c4089685091f9e67a2d88c4b62933da4481751eda6103&X-Amz-SignedHeaders=host&x-id=GetObject',
          position: 0.2353
        },
        contents: [
          // ... content blocks
        ],
        taxonomies: [],
        created: 1650250500000,
        updated: 1653121200000
      },
    },
  },
  // ... etc
]

The individual page data can be accessed in Astro.props .

TypeScript

import { getParentPage, getChildPagesStaticPaths } from "astronotion/api";
import { NotionBlocks } from "astronotion/components";

export async function getStaticPaths() {
  // ... same as props example
}

const { pageData, pageType } = Astro.props;
const { title, icon, contents, created } = pageData;

HTML

<article>
  <h1>{`${icon} ${title}`}</h1>
  <time datetime={new Date(created).toISOString()}>
    {new Date(created).toLocaleDateString()}
  </time>
  <NotionBlocks data={contents} />
</article>

Astro page component usage

This method works if all of these conditions are met:

Run in an Astro page
Run in a file named [...fullSlug].astro
- You can use a different file name; make sure you modify the returned params value and change the fullSlug property to match your new file name.
Returned from an exported getStaticPaths functionNote that you still have to create pages/journal/index.astro to have mysite.com/journal .

Example:

pages/journal/index.astro —> creates mysite.com/journal
pages/journal/[...fullSlug].astro —> creates mysite.com/journal/1cf6f82e-ffc2-4ad4-aea5-a50f88198a7b (and other page IDs)

💡

This method is best suited for one-off use. If you have multiple pairs of parent-child pages (eg. journal , talks , reviews ), it might be redundant to create two page files for each pairs ( journal/index.astro , journal/[...fullSlug].astro , talks/index.astro .…etc 😪). A possible alternative is an undocumented method getManyBaseStaticPaths , which enables you to run this from a single page file. It will be polished and documented in the next minor release.

← Prev: Getting Started | Next: Components →