Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt

Use this file to discover all available pages before exploring further.

The Notion resource exposes a Notion workspace as a virtual filesystem mounted at a prefix such as /notion/. For API key setup, see Notion Setup.

​
Config

import os

from mirage import MountMode, Workspace
from mirage.resource.notion import NotionConfig, NotionResource

config = NotionConfig(api_key=os.environ["NOTION_API_KEY"])
resource = NotionResource(config=config)
ws = Workspace({"/notion": resource}, mode=MountMode.WRITE)
FieldRequiredDefaultDescription
api_keyyesNotion integration token
base_urlnohttps://api.notion.com/v1API base URL

​
Filesystem Layout

/notion/
  pages/
    <page-title>__<page-id>/
      page.json
      <child-page-title>__<child-id>/
        page.json
        ...
Example: 
/notion/
  pages/
    Project-Roadmap__a1b2c3d4/
      page.json
      Q1-Goals__e5f6g7h8/
        page.json
      Q2-Goals__i9j0k1l2/
        page.json
    Meeting-Notes__m3n4o5p6/
      page.json
The hierarchy mirrors Notion’s page tree. Each page directory contains a page.json file with the page metadata and content. Child pages appear as nested directories.

​
Cache

Uses IndexCacheStore for page metadata. No separate content cache - file content caching is handled by the workspace IOResult mechanism.

​
Example

import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.notion import NotionConfig, NotionResource

load_dotenv(".env.development")

config = NotionConfig(api_key=os.environ["NOTION_API_KEY"])
resource = NotionResource(config=config)


async def main():
    ws = Workspace({"/notion": resource}, mode=MountMode.WRITE)

    # List top-level pages
    r = await ws.execute("ls /notion/pages/")
    print(await r.stdout_str())

    # Read a page
    r = await ws.execute(
        'cat "/notion/pages/Project-Roadmap__a1b2c3d4/page.json"'
    )
    print(await r.stdout_str())

    # Search across all pages
    r = await ws.execute('grep "deadline" /notion/pages/')
    print(await r.stdout_str())

    # Tree view
    r = await ws.execute("tree -L 2 /notion/")
    print(await r.stdout_str())

    # Create a new page
    r = await ws.execute(
        'notion-page-create --parent_id a1b2c3d4'
        ' --title "New Page" --content "Hello from Mirage"'
    )
    print(await r.stdout_str())

    # Append content to an existing page
    r = await ws.execute(
        'notion-block-append --page_id a1b2c3d4'
        ' --content "Appended paragraph"'
    )
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

​
Shell Commands

Standard commands available on the mounted Notion tree:
CommandNotes
lsList pages and child pages
catRead page.json content
head / tailFirst/last N lines
grep / rgSearch across pages
jqQuery page JSON fields
wcLine/word/byte counts
statFile metadata
findRecursive search with -name, -maxdepth
treeDirectory tree view
Resource-specific commands:

​
notion-page-create

Create a new page under a parent page.
OptionRequiredDescription
--parent_idyesParent page ID
--titleyesPage title
--contentnoInitial paragraph content

​
notion-block-append

Append content blocks to an existing page.
OptionRequiredDescription
--page_idyesTarget page ID
--contentyesText content to append

​
notion-comment-add

Add a comment to a page.
OptionRequiredDescription
--page_idyesTarget page ID
--textyesComment text
Search for pages by title.
OptionRequiredDescription
--queryyesSearch query