notion-to-astro

So you've written your documentation in Notion but want to switch to Astro Starlight to publish it. So have we! This is the script we used to convert from one to the other. Here's what it does:

Notion	Astro Starlight
File names include UUIDs	Clean file names
Title is the first h1 heading	Title is in YAML frontmatter
Embeds are self-links	Embeds are HTML
Exports <aside></aside> elements	Wants ::note syntax
Links & images are URL-encoded	They aren't

Notion bugs

This fixes a bug in Notion: if you have a link in Notion, and the link text is an inline code span, like in markdown:

[`getTest`](https://google.com/)

Notion messes this up and outputs this instead:

`[getTest](https://google.com/)`

So any roughly Commonmark Markdown implementation will render the latter as the markdown raw text rather than the intended link.

YouTube embeds

This is kind of opinionated about YouTube embeds: it compiles them to lite-youtube-embed elements. So an embed will end up looking like:

<lite-youtube videoid="ogfYd705cRs"></lite-youtube>

So, this assumes that you're using lite-youtube-embed. Which you should because it's great. In Astro Starlight, we configure lite-youtube-embed like this:

starlight({
  // …
  head: [
    {
      tag: "script",
      attrs: {
        src: "https://cdn.jsdelivr.net/npm/lite-youtube-embed@0.3.0/src/lite-yt-embed.min.js",
        defer: true,
      },
    },
    {
      tag: "link",
      attrs: {
        href: "https://cdn.jsdelivr.net/npm/lite-youtube-embed@0.3.0/src/lite-yt-embed.min.css",
        rel: "stylesheet",
      },
    },
  ],
});

If you need this to have customizable behavior instead, happy to accept a PR.

Install

npx @valtown/notion-to-astro

Usage

npx @valtown/notion-to-astro --help

One-pass

This is intended to be run once in order to start a conversion, and then you'd do some manual tweaking. It isn't a solution to maintain content in Notion while publishing with Starlight: that would require something a lot more complicated.

See also

• notion-to-md - this takes a different path of exporting Markdown from the Notion API, rather than using Notion's default Markdown exports.