notion-publish

Publishes .giantmem markdown docs into a Notion page tree via a local MCP server.

Updated Jan 15, 2026
One-click install
npx skills add https://github.com/bearded-giant/claude-code-config --skill notion-publish-bearded-giant
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: notion-publish
Source: https://github.com/bearded-giant/claude-code-config/tree/main/skills/notion-publish
Command: npx skills add https://github.com/bearded-giant/claude-code-config --skill notion-publish-bearded-giant

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Keeping local markdown documentation in sync with Notion requires manual copy-paste and page organization. This Skill automates pushing .giantmem docs into a structured Notion page tree (repo > worktree > feature > doc) through the local notion-multi-mcp server, with policy-driven gating so only eligible docs publish. ## Core Features & Use Cases - Policy-driven publishing: A YAML config decides which doc classes publish automatically on write (via hook) versus on user request, with frontmatter overrides and exclusion regexes. - Tree upserts with caching: Resolves parent pages by walking a cached parent_path map, creating container pages as needed, and upserts docs by the notion: URL stored in frontmatter. - Dual index surfaces: Rebuilds both a catalog page and a Docs catalog database after every push, with row pointers stored in each doc's own frontmatter. - Use Case: After finishing a design doc in .giantmem/features/auth/, say "publish to notion" and the doc appears under Claude Artifacts with its catalog row updated and the Notion URL written back to the file. ## Quick Start Publish my current .giantmem design doc to Notion and update the catalog index.

Frequently Asked Questions about notion-publish

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I publish markdown docs to Notion automatically?

Run /notion-publish with file paths, --feature, or --dirty flags, or say "publish to notion". Docs with publish: true frontmatter or auto-class kinds publish on write via the PostToolUse hook; on_request types publish only when explicitly asked.

How does Notion page upsert avoid duplicate pages?

The skill upserts by the notion: URL stored in each doc's frontmatter. Existing page IDs trigger a replace_content update; missing IDs create a new page under the resolved parent, and the URL is written back to frontmatter.

Which Notion MCP server does this skill use?

It uses the local notion-personal server (wrangler on localhost:8787, kept alive by launchd). It never falls back to the hosted notion server, which belongs to a different workspace.

What happens when the local Notion MCP server is down?

Publishing stops and reports the failure; auto-class docs stay local and dirty until the next --dirty run. Recovery involves checking localhost:8787/health and restarting the launchd service com.bryan.notion-mcp.

Can I preview what will publish before pushing to Notion?

Yes, the --dry-run flag prints a table of gate decisions including class, publishable status, reason, dirty state, and parent_path without pushing anything. Use --force to override a gate rejection for an explicit user request.