Auto-populate your Github readme with data fetched from a remote notion database.

Safwan Shaheer — Tue, 04 May 2021 16:44:16 +0000

Hello everyone. This article will share how I managed to auto-populate a Github readme learned section using data fetched from a remote notion database using a GitHub action that I created using Typescript.

Github

Steps

In Repository File

1. Add the following content to your `README.md`

## What I have learned so far

<!--START_SECTION:learn-->
<!--END_SECTION:learn-->

2. Configure the workflow

name: 'Github Readme Updater'
on:
  workflow_dispatch:
  schedule:
    - cron: '0 0 * * *' # Runs Every Day
jobs:
  update_learn:
    name: 'Update learn section'
    runs-on: ubuntu-latest
    steps:
      - name: 'Fetching Repository Contents'
        uses: actions/checkout@main
      - name: 'Learn Section Updater'
        uses: 'devorein/github-readme-learn-section-notion@master'
        with:
          database_id: '6626c1ebc5a44db78e3f2fe285171ab7'
          token_v2: ${{ secrets.NOTION_TOKEN_V2 }} # Required only if your database is private

TIP: You can test out using this template that I've created just for this purpose.

In your notion account

1. Create a full-page database

NOTE: Your database must maintain the following structure/schema

2. Get the id of the database

3. Add it in the workflow file

with:
  database_id: '6626c1ebc5a44db78e3f2fe285171ab7'

Follow the rest of the steps only if your database is not public, if its public you don't need to set the token_v2

To make your database public

Navigate to the database in your notion account
Click on Share at the top right corner
Click on the Share to Web button.

1. Get your notion `token_v2`

NOTE: By no means should you share or expose your notion token_v2. If you feel like you've done so accidentally, immediately log out from that account in all of your devices.

Follow the steps below to obtain your token_v2:

Open up the dev tools of your preferred browser.
Go to the Application > Cookies section.
There you'll find a token_v2 cookie.

NOTE: Its highly recommended to store your token_v2 as a github secret rather than pasting it in your workflow file.

2. Create a github secret to store `token_v2`

navigate to the url https://github.com/<USERNAME>/<REPO-NAME>/settings/secrets/actions
Click on New repository secret
You can name your secret as anything you want
Paste the token_v2 value in the Value textarea
Use the secret in your workflow file

with:
  token_v2: ${{ secrets.NOTION_TOKEN_V2 }} # The secret was named NOTION_TOKEN_V2

Outcome

If you follow all the steps properly your readme should look something like this.

Hope this was helpful to you. That's all from me for now.

The code for the Github action is here. Feel free to submit a pull request or open a new issue, contributions are highly appreciated and more than welcome. Thank you for reading.

Open source ts based unofficial notion API

Safwan Shaheer — Thu, 17 Dec 2020 13:32:02 +0000

Nishan is an open-source notion API built with typescript, axios, and node to automate almost all the CRUD functionalities the notion client provides by itself.

Reasons

As an avid notion user and a front end developer, I've always wanted to automate a lot of my workflow using Notion's native API. I have a pretty complex setup that requires a lot of manual steps, which me being a developer just could not consider as an option.

Motivation

When I started looking for the API I was a bit surprised to find that there is none, at least by the official notion team, but plenty of open-source ones, and very few for javascript where I am most comfortable. Unfortunately, most of them supported only reading data but lacked other CRUD features. So, I decided to build one from scratch using Axios as the HTTP client and javascript.

Journey

Stack

Writing it in plain JS seemed like a good idea initially, (as I never could have imagined I would be working on this library for over a month). But soon enough it got really out of hand and I ran into errors here and there. The most frustrating was the manual testing. I had to manually test whether all of the API worked properly or not, which was really not that fun. Finally, I believe after 2 weeks into it I decided to convert the whole project into typescript and never looked back.

Process

The first few days were incredibly rough. I had no idea what to do as I've never done something like this ever before. But after dabbling with the notion client for a bit, seeing each request that happens when I do something in the client and analyzing the headers, I began to grasp it little by little, and after a month of work, I am proud to say that while it's definitely not gonna have all the features of the native API, it does provide a lot.

Features

Optimal caching to reduce unnecessary requests
CRUD features for all types of data eg Space, User, Page, Block, etc etc
Easy to use API providing methods for almost everything
Minimal setup (you only require your notion token)
Types to represent almost everything within notion
An internal stack to batch operations and send a single request to the server with the appropriate payload.

Usage

Please note that this library has not been published as an npm package yet as I feel the API is still constantly evolving. So you have to clone the repo to use it.

const Nishan = require("./dist");
(async(){
  const nishan = new Nishan({
    token: /* Paste your copied token here, you can obtain it from devtools > Application > Cookies > notion.so > token_v2 */,
    timeout: 500 /* Timeout between each request */
  });
// Get the notion user using predicate
  const user = await nishan.getNotionUser((user)=>user.given_name === "Safwan");
// Get the workspace using predicate
  const space = await user.getSpace((space) => space.name === `Developer`);
// Get the root pages from the selected workspace based on the predicate
  const troot_pages = await space.getTRootPages((troot_page)=>troot_page.type === "page" && troot_page.properties.title[0][0] === "My Page");
// Delete the root page
  await troot_pages.page[0].delete();
})()

This is just a glimpse of what is possible with Nishan, I've tried to add CRUD methods for everything required (apart from a few I'm currently working on).

Disclaimer

This is still a project in progress and the docs do require a lot of love. Although the API is pretty much fixed it might change drastically in the future. Please use this library with caution as you might end up manipulating your notion data in irreversible ways. Also, be on the lookout for the official API as that will definitely be a lot better than what I've managed myself.

Conclusion

I know my work will become invalidated within a couple of months when the official API comes out, but this journey was a lot of fun plus I learned a ton from it. It would be wonderful if you could check it out. Any sort of feedback and suggestions is more than welcome. Thank you and have fun automating, cheers.

Repo

Doc

Forem: Safwan Shaheer