https://github.com/pirafrank/notion-to-jekyll
A tool to manage Jekyll drafts and posts (including assets) via Notion
https://github.com/pirafrank/notion-to-jekyll
jekyll jekyll-plugin jekyll-plugins notion notion-api notion-blog plugin plugins
Last synced: 3 months ago
JSON representation
A tool to manage Jekyll drafts and posts (including assets) via Notion
- Host: GitHub
- URL: https://github.com/pirafrank/notion-to-jekyll
- Owner: pirafrank
- License: mit
- Created: 2024-03-09T10:46:30.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-05-08T22:46:20.000Z (about 1 year ago)
- Last Synced: 2025-02-28T22:10:29.306Z (3 months ago)
- Topics: jekyll, jekyll-plugin, jekyll-plugins, notion, notion-api, notion-blog, plugin, plugins
- Language: JavaScript
- Homepage: https://fpira.com/projects
- Size: 119 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Notion-to-Jekyll
A tool to manage Jekyll drafts and posts (including assets) from Notion.
## What it does
- Converts Notion pages to Jekyll markdown
- Extract Notion properties and uses them to create post frontmatter (e.g. Jekyll category and tags)
- Download and persist to Jekyll repo Notion block assets (e.g. images, files, PDFs)
- SEO image compatibility (compatibility depends on your Jekyll post template)
- may a couple of other things I am missing rn.
## How
It uses the official [Notion SDK](https://www.npmjs.com/package/@notionhq/client) to fetch data from Notion, the [notion-to-md](https://github.com/souvikinator/notion-to-md) package to convert pages to markdown. Finally, it performs the necessary checks and adds the required front matter to make it a suitable Jekyll post on the blog.
It is designed to be run by a GitHub Actions workflow on a schedule or triggered by a webhook (via the `repository_dispatch` event).
## Usage
```sh
npm run app
```
## Configuration
The script requires the following environments variables to be set:
- `NOTION_TOKEN` is the Notion integration auth web token.
- `NOTION_DATABASE_ID` is the ID of the Notion database to fetch blog posts from.
- `RELATIVE_DATE` is an int as string to determine the date of post to fetch.
- `0` means the date will be the current date;
- a negative number means the date will be the current date minus the number of days;
- a positive number means the date will be the current date plus the number of days.
- `SITE_URL` is the URL of the website, including protocol. It is used to generate the `permalink` front matter.
Required configuration (optional when running in GitHub Action):
- `JEKYLL_ROOT` is the root of the Jekyll directory. It is used to determine the location of `POSTS_DIR` and `DRAFTS_DIR` among the other things. When running in GitHub Action, it defaults to `${{ github.workspace }}`.
Optional configuration, with default values:
- `SITE_BASEURL` is the base URL of the website, appended to `SITE_URL` above.
- `DRAFTS_DIR` is the Jekyll directory where drafts are stored. Defaults to `_drafts`.
- `POSTS_DIR` is the Jekyll directory where posts are stored. Defaults to `_posts`.
- `ASSETS_DIR` is the Jekyll directory where assets are stored. Defaults to `assets`.
- `PUBLISH_TO_POSTS` is a boolean to determine where converted pages should be published to. If `true`, to `POSTS_DIR` directory. To `DRAFTS_DIR` otherwise.
- `NOTION_TO_JEKYLL_USER` is the user used to filter out pages published by this app. This to avoid infinite loops. Defaults to `notion-to-jekyll`. It must exist in Notion.
- `NOTION_PAGE_TYPE` is the type of pages to fetch. Defaults to `Blog post`. It must exist in Notion.
- `NOTION_READY_STATUS` is the status used to filter out pages that are ready to be published. Defaults to `Ready`. It must exist in Notion.
- `NOTION_DONE_STATUS` is the status used to filter out pages that are already published. Defaults to `Done`. It must exist in Notion.
## GitHub Action
The script can be run as a step in a GitHub Actions workflow. For example:
```yaml
- name: Notion to Jekyll
uses: pirafrank/notion-to-jekyll@v1
id: notion_to_jekyll
with:
notion-token: ${{ secrets.NOTION_TOKEN }}
notion-database-id: ${{ vars.NOTION_TO_JEKYLL_DATABASE_ID }}
publish-to-posts: ${{ vars.NOTION_TO_JEKYLL_PUBLISH_TO_POSTS }}
relative-date: ${{ vars.NOTION_TO_JEKYLL_RELATIVE_DATE }}
site-url: "https://fpira.com"
assets-dir: "static/postimages"
```
The action outputs the following variables:
```yaml
- name: Print output variables
env:
# string with space-separated list of changed or added files
CHANGED: ${{ steps.notion_to_jekyll.outputs.changed }}
# string with space-separated list of deleted files
DELETED: ${{ steps.notion_to_jekyll.outputs.deleted }}
# boolean to string, 'true' if the script is running in dry-run mode
DRY_RUN: ${{ steps.notion_to_jekyll.outputs.dry-run }}
run: |
echo "CHANGED=$CHANGED"
echo "DELETED=$DELETED"
echo "DRY_RUN=$DRY_RUN"
```
Check the `action.yml` file for more configuration info.
**Tip:** use it in a scheduled workflow, or in one with a `repository_dispatch` event. This allows you to make it run periodically, or to trigger the workflow via a webhook.
```yaml
on:
repository_dispatch:
types: notion-to-jekyll
```
## LICENSE
MIT