Sync notion or docs to jekyll

Technical teams and content collaborators often prefer writing in tools like Notion or Google Docs due to their rich WYSIWYG editors, real-time collaboration, and familiarity. However, final publication often happens in a more structured, version-controlled platform like Jekyll on GitHub Pages. Bridging the gap between these two environments can unlock huge workflow benefits.

Common Challenges in Documentation Workflow

• Writers use Notion or Docs, but engineers prefer Markdown.
• Manual copy-pasting introduces formatting inconsistencies.
• Docs become outdated because syncing is sporadic.
• Content updates require developer involvement.

What If You Could Automate It?

By syncing Google Docs or Notion to your Jekyll content repository automatically, you can:

• Empower non-technical contributors to update documentation.
• Maintain centralized formatting and publishing logic in Jekyll.
• Keep everything version-controlled in Git.
• Reduce publishing lag between content creation and visibility.

Syncing from Google Docs

Step 1: Prepare the Docs

Ensure your Google Docs have a consistent structure:

• Use Heading 1 for title, Heading 2 for sections.
• Insert inline code and code blocks using Google Docs styling.
• Avoid using tables unless you will manually convert them later.

Step 2: Export Google Docs as Markdown

Use a tool like gdoc2md or Docs to Markdown (a Google Docs add-on) to convert your content into clean Markdown format compatible with Jekyll.

Step 3: Organize the Markdown Files

Place exported files into appropriate directories like _posts or _docs, depending on your content model.

docs/
├── getting-started.md
├── deployment-guide.md
├── integrations.md

Step 4: Add Jekyll Front Matter

Edit the top of each file to include front matter metadata:

---
title: "Getting Started"
layout: doc
description: "Learn how to set up the system quickly"
category: docs
---

Step 5: Automate with Google Apps Script (Optional)

You can automate exports via Apps Script that pushes converted Markdown to a GitHub repository using API tokens.

Syncing from Notion

Option 1: Manual Export to Markdown

Notion allows direct Markdown export of pages or databases. Use the “Export” function and choose “Markdown & CSV”. Then move the exported folder contents to your Jekyll site and adjust the structure.

Option 2: Use Notion API

For automatic sync, you can use Notion’s public API:

• Create an integration token.
• Share the desired pages or databases with the integration.
• Use tools like Notion API Worker or write your own Node.js script to fetch content.

Convert JSON to Markdown

Notion API returns structured blocks in JSON. Use libraries like notion-to-md or notion-md-exporter to convert blocks into Markdown format.

Automating the Pipeline with GitHub Actions

Once you have a script that can fetch and convert external content into Markdown, you can set up a GitHub Action that runs on a schedule:

name: Sync Notion to Jekyll

on:
  schedule:
    - cron: '0 * * * *'  # every hour

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v2

      - name: Run Notion to Markdown sync
        run: |
          npm install
          node sync-notion.js

      - name: Commit changes
        run: |
          git config user.name "auto-sync"
          git config user.email "[email protected]"
          git add .
          git commit -m "Update docs from Notion"
          git push

Preserving Consistent Layout in Jekyll

Even though the source comes from Notion or Google Docs, the presentation still relies on your Jekyll layouts. This means you can:

• Style all synced docs uniformly.
• Include navigation menus or table of contents automatically.
• Apply syntax highlighting using Rouge or Prism.js.

Example: Display Synced Doc with Navigation

Your layout file doc.html can include a sidebar generated from front matter or collection index.

{% assign docs = site.docs | sort: "title" %}
<ul>
  {% for doc in docs %}
    <li><a href="{{ doc.url }}">{{ doc.title }}</a></li>
  {% endfor %}
</ul>

Versioning and Branch Control

You can sync changes into a separate branch like sync-content and review PRs manually before merging to main. This ensures quality control and prevents accidental overwrites of live content.

Content Governance Tips

• Use a naming convention for synced files, like notion-integration-2025.md.
• Tag synced content in front matter with source: notion or source: gdocs.
• Regularly lint and format the Markdown before merging.

Conclusion: Best of Both Worlds

By syncing documentation from Google Docs or Notion into Jekyll, you get the collaborative ease of rich editors and the precision of structured, versioned publishing. Whether you're a startup scaling fast or a solo developer maintaining tutorials, this approach reduces friction between content and deployment.

What to Build Next

• Notion-based CMS for a Jekyll blog.
• Embed synced Google Docs inside Jekyll with iframe fallback.
• Build a headless publishing workflow using GitHub API + Google Docs.

This automation enables a collaborative workflow that’s still clean, fast, and developer-friendly—true to the spirit of Jekyll and GitHub Pages.