README.md

Notion to Markdown: a tool for fetching Notion page trees, written in Clojure. Can be used to sync Readme files.

Concepts

Notion API requires a page-id and a notion-secret to be able to access a page’s content:

• If the url is https://www.notion.so/Testnet-8ddeb7e276c34685b460c5380f592f9d, then page-id is 8ddeb7e276c34685b460c5380f592f9d.

• notion-secret is obtained in Notion’s workspace configuration. Go to My Integrations & add a New Integration. After you follow the steps there, you’ll end up with a secret string that looks like this: secret_j2oz4j12ddjoalmdp91phesdahjlcsdwq0u11ay3Df8.

Usage

Lein

Add this to your dependencies:

  [com.flexiana/notion-to-md "0.1.11"]

Alias it with the following:

  :profiles {:local
               {:dependencies
                [[com.flexiana/notion-to-md "0.1.11"]]}}
    :aliases {"notion-to-md"     
              ["with-profile" 
               "local" 
               "run" 
               "-m" 
               "notion-to-md.core"]}

Invoke it with lein notion-to-md.

Pass arguments either by:

• NOTION_PAGE_ID and NOTION_API_SECRET environment variables.

   export NOTION_PAGE_ID="<page-id>"
   export NOTION_API_SECRET="<notion-secret>"
   lein notion-to-md
  

  This is the way to go when integrating GitHub actions. See https://docs.github.com/en/actions/learn-github-actions/environment-variables

• Or as parameters:

   lein notion-to-md <notion-secret> <page-id>
  

Outputs

• The main notion page (referenced by the NOTION_PAGE_ID environment variable) is going to generate the README.md file.

• The sub pages are going to be created inside the docs/readme/ folder.

Recommendations

1. Avoid using "link_to_page". Use “sub pages” instead. Or use “mention” if you want to make a link. Reason: A "link_to_page" is going to be inlined for technical reasons (the link's title is not easy to get). So, just use “sub pages” or “mentions” for the README files.

Unsupported Notion types

notion-to-md does not support the types below:

1. "table_of_contents" doesn’t provide data.

2. "table" provides "unsupported" for each row.

3. "child_database" is complex and probably is not going to be used in a README.md so it's not supported by notion-to-md.

4. "link_preview"

Allowing access to Notion API

To interact with the API, we have to give the integration user access to page(s) we want to fetch. To achieve this, follow the steps below.

1. Go to the page you want to fetch.

2. Click “Share” at the top-right corner.

3. Click “Invite”.

4. Select the Integration user you have added prior to this.

Notes

The tool automatically fetches all sub pages as well.

References

• Markdown reference: https://www.markdownguide.org/basic-syntax/

• API reference: https://developers.notion.com/reference/block

Authors

Brought to you with ❤️ by Flexiana.

License

Copyright 2022 Flexiana.

Written and distributed under Apache License 2.0.

How to guides [internal]

Update Readme on GitHub