noblog-starter

noblog-starter is a blog boilerplate for Astro that turns a Notion database into a fast static site at build time, with plain Markdown posts as a fallback when you'd rather skip Notion entirely.

What is noblog-starter?

noblog-starter is an Astro blog starter built on the noblog CLI, which fetches posts from a Notion database and writes them into a local content store that Astro builds into a static site. It takes a Notion integration token and database ID (or ordinary Markdown files with matching frontmatter) as input and outputs a GitHub Pages-ready static blog. There is no server, admin panel, or copy-paste step: the Notion database is the CMS, and noblog generate is run explicitly rather than as part of dev or build.

Key Features

• Astro + Tailwind CSS stack — routes for an About page, blog index, tags/search, RSS, and generated post Markdown live in src/pages/, with Tailwind tokens in src/styles/global.css.
• Search and multi-tag filtering — a dedicated /tags page supporting multi-select tag filters that use AND semantics.
• Recursive Notion child pages — child pages render as inline links inside ordinary paragraphs or as subpage link cards when a marker-only paragraph is used; the default marker is ⸎ and legacy kaomoji markers still work.
• Year archive rail — an ambient, responsive year watermark alongside the archive listing.
• Article reading experience — distraction-free layout with no footer, a sticky table of contents, Shiki syntax highlighting, and MathJax math rendering.
• Light/dark theme without flash — theme switching that avoids a flash on page load.
• RSS feed at /rss.xml — served as XML for feed readers, not as a styled HTML page.
• No-JavaScript core content — core article content remains readable without JavaScript, and hand-written Markdown posts share the same layout, search, tags, and RSS.

Who is it for?

• Notion-based writers: keep drafting posts in a Notion database and let the build publish them as a static blog with no CMS login or admin panel.
• Markdown-first developers: write posts under src/pages/posts/ with the MarkdownPostLayout.astro frontmatter (layout, title, pubDate, tags, description) and get the same tags, search, and RSS.
• GitHub Pages users: create a repo from the template, set BASE_PATH and SITE_URL repository variables, add NOBLOG_DATABASE_ID and NOTION_API_SECRET secrets, and deploy via the included Actions workflow.

What can you do with noblog-starter?

• Publish a Notion-backed blog: duplicate the Noblog database, connect a Notion integration to it, and run pnpm noblog:generate followed by pnpm build to produce a static site.
• Render a Notion bio page: set the SELFIE_PAGE variable to a published database page's exact title to render it over public/selfie.md as the About page at build time.
• Auto-refresh expiring assets: the deploy workflow rebuilds every four hours so Notion-hosted file and image URLs stay valid; the cron schedule is editable in .github/workflows/deploy.yml.

How does noblog-starter work?

Copy .env.example to .env and fill in the Notion token and database ID, run pnpm install and pnpm noblog:check to validate noblog.yaml, then pnpm noblog:generate to fetch content into .noblog/pages/, which is exposed to src/pages/posts/ via symlinks. pnpm dev starts Astro; pnpm build runs astro check and builds.

Pros and cons

• Pros: no server or admin panel, core content readable without JavaScript, explicit generation step decoupled from the frontend build, plain Markdown path available.
• Cons: requires Node.js 24 or newer plus pnpm, and Notion content needs an integration token and database ID. Generated paths are gitignored, so hand-written Markdown posts must be force-added. Math spacing inside delimiters needs \ because ~ does not work.

FAQ

Does noblog-starter require Notion?

No. Notion is optional. You can write plain Markdown posts under src/pages/posts/ with frontmatter matching MarkdownPostLayout.astro, and they use the same layout, search, tags, and RSS. Notion simply removes the manual publishing step.

What are the requirements to run noblog-starter?

You need Node.js 24 or newer, pnpm, and a Notion integration token plus database ID if you generate content from Notion. The noblog CLI is pinned in optionalDependencies and installed from npm, so no sibling checkout is required.

Why does the Notion database ID need dashes?

The documented setup says the ID must be pasted with dashes, because current Notion API versions reject the 32-character undashed form and fail the build with a path.database_id should be a valid uuid error.

Which posts appear in the RSS feed?

Top-level database posts appear in the blog index, search, and RSS. Recursive child pages are directly routable and linked from their parent posts but are excluded from discovery feeds. The feed itself is served as XML at /rss.xml.