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 |
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.
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/[email protected]/src/lite-yt-embed.min.js",
defer: true,
},
},
{
tag: "link",
attrs: {
href: "https://cdn.jsdelivr.net/npm/[email protected]/src/lite-yt-embed.min.css",
rel: "stylesheet",
},
},
],
});If you need this to have customizable behavior instead, happy to accept a PR.
npx @valtown/notion-to-astronpx @valtown/notion-to-astro --helpThis 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.
- notion-to-md - this takes a different path of exporting Markdown from the Notion API, rather than using Notion's default Markdown exports.