Writing Good Slugs

In this first version, notion2svelte treats Slugs at face value. If your page has a Slug of “foo/bar/baz,” notion2svelte will save a file at src/routes/foo/bar/baz/+page.svelte. This has subtle consequences…which can be ignored if you follow one simple rule:

1.Use site-relative Slugs, by always starting them with /

❌ blog/best-post-ever

✅ /blog/best-post-ever

Keep reading for details. Or not. ↑ This is all you really need to know. 😎

Use site-relative Slugs

Relative links are important because they decouple internal links from the site’s domain. However, there are two kinds of relative: site-relative, and page-relative. Let’s start with the more problematic: page-relative links.

❌ Page-relative links

Say we have a page in our Notion database with the Slug, mantis-shrimp. Running notion2svelte gets you…

A Svelte page: src/routes/mantis-shrimp/+page.svelte

Links to this page will (probably*) look something like: <a href="link-target">Link</a>

*I say probably, because it’s up to you how you implement your Link component.

Now let’s say that you have two pages linking to “link-target”, one and two, like so

├── src
│   └── routes
│       ├── one.svelte
│       ├── mantis-shrimp/+page.svelte
│       └── subpages
│           ├── two.svelte
│           …
  javascript

To keep things concrete, let’s say you publish your site at https://foo.io. When you click the href="mantis-shrimp" link in the page generated from one.svelte (https://foo.io/one), the URL resolves to https://foo.io + mantis-shrimp ⇒ https://foo.io/mantis-shrimp. So far so good!

But now let’s look at the same link (again, href=”mantis-shrimp”) clicked from https://foo.io//subpages/two. Here, the relative root is no longer https://foo.io, but https://foo.io/subpages. Now, when we click the link, it resolves to htttps://foo.io/subpages/mantis-shrimp which, of course, does not exist, leading to a 404 😥.

🌞👍 Site-relative links

When you prepend a Slug with /, notion2svelte creates site-relative links. Now, instead of <a href="link-target">Link</a>, we have <a href="/link-target">Link</a>, so, no matter where you link to the ”target” page, the link will be resolved using the site root, leading us infallibly to https://foo.io/link-target.

Which is what we want.