<aside> ⚠ This file is linked to Github. Changes must be made in the markdown file to be permanent.
</aside>
As projects scale it's important to keep documentation accessible and up-to-date. README's and other markdown files that live alongside source can be extremely useful for building context as you work throughout a repository.
For many organizations Notion is the central store for documentation. This project lets engineers continue to author documentation alongside their work and also make sure it stays up to date with the broader organization documentation.
This Github action automatically scans commits for markdown changes and uses some frontmatter fields to push the changes to Notion.
It's intentionally set up to be used with an internal integration so document data stays within your organization.
Head to the Notion dashboard and create a new internal integration. It will need read, update, and insert capabilities.
This workflow will run for every push to main. It is dependent on having access to git and the repo being checked. It will check the latest commit on whichever branch is checked out for markdown changes. Make sure to add fetch-depth: 2 for the diff check to work correctly.
on:
push:
branches:
- main
jobs:
push_markdown_job:
runs-on: ubuntu-latest
name: Push Markdown to Notion
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 2
- name: Push Markdown to Notion
uses: JoshStern/[email protected]
id: push_markdown
with:
notion-token: ${{ secrets.NOTION_TOKEN }}
A Notion page needs to be created before markdown content will be synced to it. You can add your integration to a root page or to each synced page.
You're now ready to start pushing changes to Notion! You can add the following frontmatter fields to an existing markdown file or to a new one.
---
notion_page: <https://www.notion.so/><your_path>
title: <Your Title>
---
# My README
This content will by synced to Notion!
Repeat steps 3 and 4 for new markdown files.