// Use when converting a Notion markdown export to a Docusaurus blog post for the dbt docs site, or when given a path to a Notion export folder/file.
| name | converting-notion-to-docusaurus-blog |
| description | Use when converting a Notion markdown export to a Docusaurus blog post for the dbt docs site, or when given a path to a Notion export folder/file. |
Automates conversion of Notion markdown exports into properly formatted Docusaurus blog posts for docs.getdbt.com. Handles frontmatter generation, image processing, content cleanup, and file organization.
Parse the markdown file and locate the accompanying image folder (same name as the .md file, without the hash suffix).
From the Notion export, extract:
Search website/blog/authors.yml for a matching name from the Owner field.
If not found, prompt user:
Author "[Name]" not found in authors.yml.
How would you like to proceed?
1. Enter details now (name, title, photo URL, LinkedIn)
2. Scaffold empty entry to fill in manually later
Option 2 creates:
firstname_lastname:
name: Full Name
title: "" # TODO
image_url: /img/blog/authors/firstname-lastname.png # TODO
socials:
linkedin: "" # TODO
page: true
Slug guidelines: Keep 2-4 words, include primary keywords, drop "introducing", "a", "the", "how to".
dbt-agent-skillsgit-branching-strategies-dbtTag selection: Check website/blog/categories.yml for available tags and their descriptions. Select the most appropriate tag based on the post content. Fall back to analytics craft only if no other tag fits.
For each image in the Notion export folder:
skills-mcp-diagram.png not 74cb2aed-fe53-481b-89d0-eefd0054e0c2.png)website/static/img/blog/YYYY-MM-DD-slug/Copy the Notion markdown file to website/blog/YYYY-MM-DD-slug.md first. This establishes the baseline for git diffs.
Apply transformation rules (see below) as individual edits to the copied file. This makes changes visible in git diff, allowing review of exactly what was modified.
Run a spellcheck on the content and fix any typos or spelling errors. Be careful to preserve technical terms, product names (dbt, MetricFlow, BigQuery), and intentional stylistic choices.
Summarize: files created, images processed, spelling corrections made, any TODO items (e.g., incomplete author entry).
Generate YAML frontmatter:
---
title: "Title from H1"
description: "A compelling sentence from the article that captures the key value or insight"
slug: seo-optimized-slug
authors: [author_slug]
tags: [appropriate-tag]
hide_table_of_contents: false
date: YYYY-MM-DD
is_featured: true
---
| Notion | Docusaurus |
|---|---|
 | <Lightbox src="/img/blog/YYYY-MM-DD-slug/semantic-name.png" width="85%" alt="generated alt text" /> |
| Image with caption on next line | Merge caption into title attribute |
| Pattern | Action |
|---|---|
| H1 title | Remove (comes from frontmatter) |
| Status/Owner/Created time block | Remove |
| Trailing sections after conclusion | Remove (internal notes) |
Code blocks with language markdown | Change to bash if shell commands |
Notion callouts (> **Note**) | Convert to :::note admonitions |
URL-encoded paths (%20) | Decode |
asterisks for emphasis (*emphasised* content) | Replace with underscores (_emphasised_ content) |
Internal Notion links (notion.so, notion.site) | Flag for review - replace with public resource links |
Absolute docs site links (https://docs.getdbt.com/...) | Convert to relative paths (/docs/..., /reference/...) |
Insert <!-- truncate --> after the introduction (1-3 paragraphs, ~150-300 words) and before the first ## heading.
Notion Export:
my-post abc123.md
my-post abc123/
image.png
image 1.png
Step 1 - Copy original:
website/blog/YYYY-MM-DD-slug.md (raw Notion content)
Step 2 - Apply edits (diffable):
website/blog/YYYY-MM-DD-slug.md (transformed)
website/static/img/blog/YYYY-MM-DD-slug/
semantic-name.png
another-semantic-name.png