narkdown 1.1.0

A tool to use Notion as a Markdown editor.

Narkdown

A tool to use Notion as a Markdown editor.

---

⚠️ NOTE: Narkdown uses customized version of notion-py created by Jamie Alexandre. That repository seems to be abandoned. Also, this is based on the private Notion API. It can not gurantee it will stay stable. If you need to use in production, I recommend waiting for their official release.

---

Features

• Auto synchronization of Notion to Github by using Github Actions and crontab.

• Format documents by using Prettier.

• Import a Notion page and save it to the desired path.

  Useful for simple markdown exporter.

• Import Notion pages from database to the desired path.

  Useful for CMS(Contents Manage System) of static pages such as blog or docs page.

  • Support import by status of content.

  • Support filter contents.

• Import "Child page" in Notion page recursively. And import "Linked page" as a Notion page link.

• Support nested block. (e.g. bulleted, numbered, to-do, toggle)

• Support syntax highlighting in code block.

Usage

Quickstart

⚠️ NOTE: the latest version of narkdown requires Python 3.5 or greater.

1. Install dependencies

   pip install narkdown

2. Get token_v2 cookie from a logged-in browser session on Notion.so.

   

3. Add config.json in root directory

   {
       "TOKEN":
       "DATABASE_URL":
       "PAGE1_URL":
       "PAGE2_URL":
       "PAGE3_URL":
       "PAGE4_URL":
       // and so on ...
   }
   

4. Use it like an example.py

   import sys
   import json
   from narkdown.exporter import NotionExporter
   
   if __name__ == "__main__":
       with open("config.json", "r") as f:
           config = json.load(f)
   
       token = config["TOKEN"]
       readme_url = config["README_URL"]
       docs_page_url = config["DOCS_PAGE_URL"]
       database_url = config["DATABASE_URL"]
   
       # Get project README.md
       NotionExporter(token, ".").get_notion_page(
           url=readme_url, create_page_directory=False
       )
   
       # Get directory README.md
       NotionExporter(token, "./docs").get_notion_page(
           url=docs_page_url, create_page_directory=False
       )
   
       # Get all contents from database
       NotionExporter(token).get_notion_pages_from_database(
           url=database_url,
           category_column_name="Category",
           status_column_name="Status",
           current_status="",
           next_status="",
           filters={},
       )
   

Format Documents

• Create package.json file to your document directory.

  • Example

  {
    "name": "narkdown-docs",
    "dependencies": {
      "prettier": "2.1.1"
    },
    "scripts": {
      "format": "prettier --write ."
    },
    "author": "younho9",
    "license": "MIT"
  }
  

• Install dependencies

  cd docs # your documents directory
  npm install
  

• Add prettier setting

  .prettierrc (example)

  {
    "printWidth": 100,
    "tabWidth": 2,
    "singleQuote": true,
    "trailingComma": "all",
    "bracketSpacing": true,
    "semi": true,
    "useTabs": false,
    "arrowParens": "avoid",
    "endOfLine": "lf"
  }
  

• Using npm scripts

  cd docs # your documents directory
  npm run format
  

Examples

• Click here.

  Example : Categorize content by "Select" property.

  • Create "Select" column and specify category by page.

    

  • Pass category_column_name to parameter.

    NotionExporter(token).get_notion_pages_from_database(
        url=database_url,
        category_column_name="Category"
    )
    

  Example : Get content by status.

  • Create "Select" column and specify status of page.

    

  • Pass status_column_name, current_status, next_status to parameter.

    NotionExporter(token).get_notion_pages_from_database(
        url=database_url,
        status_column_name="Status",
        current_status="✅ Completed",
        next_status="🖨 Published"
    )
    

  • After extract page, status will be changed.

    

  Example : Apply filter

  • Pass key, value pair of filter list to filters parameter.

    NotionExporter(token).get_notion_pages_from_database(
        url=database_url,
        filter={"Name" : "Basic Blocks"}
    )
    

  Example : Auto synchronization of Notion and Github

  • Register token_v2 and url of page to synchronize in github's secret.

    

  • Allow python files to receive arguments.

    # auto_sync.py
    
    import sys
    from narkdown.exporter import NotionExporter
    
    if __name__ == "__main__":
        token = sys.argv[1]
        database_url = sys.argv[2]
    
        """
        Get contents from the database that is in the "✅ Completed" state,
        and update it to the "🖨 Published" state.
        """
        NotionExporter(token).get_notion_pages_from_database(
            url=database_url,
            category_column_name="Category",
            status_column_name="Status",
            current_status="✅ Completed",
            next_status="🖨 Published",
            filters={},
        )
    

  • Create github actions workflow file to .github/workflows

Supported Blocks

View supported blocks by type

Block Type	Supported	Notes
Heading 1	✅ Yes	Converted to heading 2 in markdown.
Heading 2	✅ Yes	Converted to heading 3 in markdown.
Heading 3	✅ Yes	Converted to heading 4 in markdown.
Text	✅ Yes
Divider	✅ Yes	Divider after the Heading 1 is not added.
Callout	✅ Yes	Callout block will be exported as quote block with emoji.
Quote	✅ Yes
Bulleted list	✅ Yes	Support nested block.
Numbered list	✅ Yes	Support nested block.
To-do list	✅ Yes	Support nested block.
Toggle list	✅ Yes	Support nested block.
Code	✅ Yes	Support syntax highlighting.
Image	✅ Yes	Uploaded image will be downloaded to local. Linked image will be linked not be downloaded.
Web bookmark	✅ Yes	Same as link text.
Page	✅ Yes	Import "Child page" in Notion page recursively. And import "Linked page" as a Notion page link.
Table (aka database)	⚠️ Partial	⚠️ The sequence of columns is not guaranteed.
Video	❌ No
Audio	❌ No
File	❌ No
Embed other services	❌ No
Advanced	❌ No
Layout in page	❌ No

License

MIT © younho9