[docs] nav rework (sveltejs#7331)

* [docs] nav rework

- restructure nav on the left: top level sections, only show page titles
- add "on this page" nav on the right on big screens

* poor packaging got left out

* different styling idea

* padding

* move files

* move logic around etc

* simplify

* fix

* fix on this page links

* fix title

* break out getting started info, ensure on this page is always populated

Co-authored-by: Rich Harris <[email protected]>

documentation/docs/00-introduction.md → documentation/docs/10-getting-started/10-introduction.md

@@ -12,32 +12,8 @@ title: Introduction
 
 SvelteKit is a framework for building extremely high-performance web apps.
 
-Building an app with all the modern best practices is fiendishly complicated. Those practices include [build optimizations](https://vitejs.dev/guide/features.html#build-optimizations), so that you load only the minimal required code; [offline support](/docs/service-workers); [prefetching](/docs/link-options#data-sveltekit-prefetch) pages before the user initiates navigation; and [configurable rendering](/docs/page-options) that allows you to render your app [on the server](/docs/appendix#ssr) or [in the browser](/docs/appendix#csr-and-spa) at runtime or [at build-time](/docs/appendix#prerendering). SvelteKit does all the boring stuff for you so that you can get on with the creative part.
+Building an app with all the modern best practices is fiendishly complicated. Those practices include [build optimizations](https://vitejs.dev/guide/features.html#build-optimizations), so that you load only the minimal required code; [offline support](/docs/service-workers); [prefetching](/docs/link-options#data-sveltekit-prefetch) pages before the user initiates navigation; and [configurable rendering](/docs/page-options) that allows you to render your app [on the server](/docs/glossary#ssr) or [in the browser](/docs/glossary#csr-and-spa) at runtime or [at build-time](/docs/glossary#prerendering). SvelteKit does all the boring stuff for you so that you can get on with the creative part.
 
 It uses [Vite](https://vitejs.dev/) with a [Svelte plugin](https://github.com/sveltejs/vite-plugin-svelte) to provide a lightning-fast and feature-rich development experience with [Hot Module Replacement (HMR)](https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/config.md#hot), where changes to your code are reflected in the browser instantly.
 
 You don't need to know Svelte to understand the rest of this guide, but it will help. In short, it's a UI framework that compiles your components to highly optimized vanilla JavaScript. Read the [introduction to Svelte blog post](https://svelte.dev/blog/svelte-3-rethinking-reactivity) and the [Svelte tutorial](https://svelte.dev/tutorial) to learn more.
-
-### Getting started
-
-The easiest way to start building a SvelteKit app is to run `npm create`:
-
-```bash
-npm create svelte@latest my-app
-cd my-app
-npm install
-npm run dev
-```
-
-The first command will scaffold a new project in the `my-app` directory asking you if you'd like to set up some basic tooling such as TypeScript. See the FAQ for [pointers on setting up additional tooling](/faq#integrations). The subsequent commands will then install its dependencies and start a server on [localhost:5173](http://localhost:5173).
-
-There are two basic concepts:
-
-- Each page of your app is a [Svelte](https://svelte.dev) component
-- You create pages by adding files to the `src/routes` directory of your project. These will be server-rendered so that a user's first visit to your app is as fast as possible, then a client-side app takes over
-
-Try editing the files to get a feel for how everything works – you may not need to bother reading the rest of this guide!
-
-#### Editor setup
-
-We recommend using [Visual Studio Code (aka VS Code)](https://code.visualstudio.com/download) with [the Svelte extension](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode), but [support also exists for numerous other editors](https://sveltesociety.dev/tools#editor-support).

documentation/docs/10-getting-started/20-creating-a-project.md

@@ -0,0 +1,25 @@
+---
+title: Creating a project
+---
+
+The easiest way to start building a SvelteKit app is to run `npm create`:
+
+```bash
+npm create svelte@latest my-app
+cd my-app
+npm install
+npm run dev
+```
+
+The first command will scaffold a new project in the `my-app` directory asking you if you'd like to set up some basic tooling such as TypeScript. See the FAQ for [pointers on setting up additional tooling](/faq#integrations). The subsequent commands will then install its dependencies and start a server on [localhost:5173](http://localhost:5173).
+
+There are two basic concepts:
+
+- Each page of your app is a [Svelte](https://svelte.dev) component
+- You create pages by adding files to the `src/routes` directory of your project. These will be server-rendered so that a user's first visit to your app is as fast as possible, then a client-side app takes over
+
+Try editing the files to get a feel for how everything works – you may not need to bother reading the rest of this guide!
+
+### Editor setup
+
+We recommend using [Visual Studio Code (aka VS Code)](https://code.visualstudio.com/download) with [the Svelte extension](https://marketplace.visualstudio.com/items?itemName=svelte.svelte-vscode), but [support also exists for numerous other editors](https://sveltesociety.dev/tools#editor-support).

documentation/docs/01-project-structure.md → documentation/docs/10-getting-started/30-project-structure.md

@@ -1,5 +1,5 @@
 ---
-title: Project Structure
+title: Project structure
 ---
 
 A typical SvelteKit project looks like this:

documentation/docs/10-getting-started/meta.json

@@ -0,0 +1,3 @@
+{
+	"title": "Getting started"
+}

documentation/docs/03-routing.md → documentation/docs/20-core-concepts/10-routing.md

@@ -16,7 +16,7 @@ Each route directory contains one or more _route files_, which can be identified
 
 #### +page.svelte
 
-A `+page.svelte` component defines a page of your app. By default, pages are rendered both on the server ([SSR](/docs/appendix#ssr)) for the initial request and in the browser ([CSR](/docs/appendix#csr-and-spa)) for subsequent navigation.
+A `+page.svelte` component defines a page of your app. By default, pages are rendered both on the server ([SSR](/docs/glossary#ssr)) for the initial request and in the browser ([CSR](/docs/glossary#csr-and-spa)) for subsequent navigation.
 
 ```svelte
 /// file: src/routes/+page.svelte

documentation/docs/06-form-actions.md → documentation/docs/20-core-concepts/30-form-actions.md

@@ -1,5 +1,5 @@
 ---
-title: Form Actions
+title: Form actions
 ---
 
 A `+page.server.js` file can export _actions_, which allow you to `POST` data to the server using the `<form>` element.

documentation/docs/13-page-options.md → documentation/docs/20-core-concepts/40-page-options.md

@@ -2,15 +2,15 @@
 title: Page options
 ---
 
-By default, SvelteKit will render (or [prerender](/docs/appendix#prerendering)) any component first on the server and send it to the client as HTML. It will then render the component again in the browser to make it interactive in a process called **hydration**. For this reason, you need to ensure that components can run in both places. SvelteKit will then initialize a [**router**](/docs/routing) that takes over subsequent navigations.
+By default, SvelteKit will render (or [prerender](/docs/glossary#prerendering)) any component first on the server and send it to the client as HTML. It will then render the component again in the browser to make it interactive in a process called **hydration**. For this reason, you need to ensure that components can run in both places. SvelteKit will then initialize a [**router**](/docs/routing) that takes over subsequent navigations.
 
 You can control each of these on a page-by-page basis by exporting options from [`+page.js`](/docs/routing#page-page-js) or [`+page.server.js`](/docs/routing#page-page-server-js), or for groups of pages using a shared [`+layout.js`](/docs/routing#layout-layout-js) or [`+layout.server.js`](/docs/routing#layout-layout-server-js). To define an option for the whole app, export it from the root layout. Child layouts and pages override values set in parent layouts, so — for example — you can enable prerendering for your entire app then disable it for pages that need to be dynamically rendered.
 
 You can mix and match these options in different areas of your app. For example you could prerender your marketing page for maximum speed, server-render your dynamic pages for SEO and accessibility and turn your admin section into an SPA by rendering it on the client only. This makes SvelteKit very versatile.
 
 ### prerender
 
-It's likely that at least some routes of your app can be represented as a simple HTML file generated at build time. These routes can be [_prerendered_](/docs/appendix#prerendering).
+It's likely that at least some routes of your app can be represented as a simple HTML file generated at build time. These routes can be [_prerendered_](/docs/glossary#prerendering).
 
 ```js
 /// file: +page.js/+page.server.js/+server.js
@@ -83,7 +83,7 @@ Since these routes cannot be dynamically server-rendered, this will cause errors
 
 ### ssr
 
-Normally, SvelteKit renders your page on the server first and sends that HTML to the client where it's hydrated. If you set `ssr` to `false`, it renders an empty 'shell' page instead. This is useful if your page is unable to be rendered on the server (because you use browser-only globals like `document` for example), but in most situations it's not recommended ([see appendix](/docs/appendix#ssr)). If you put this into your root `+layout.js`, you create an SPA (all pages are client-side rendered only).
+Normally, SvelteKit renders your page on the server first and sends that HTML to the client where it's hydrated. If you set `ssr` to `false`, it renders an empty 'shell' page instead. This is useful if your page is unable to be rendered on the server (because you use browser-only globals like `document` for example), but in most situations it's not recommended ([see appendix](/docs/glossary#ssr)). If you put this into your root `+layout.js`, you create an SPA (all pages are client-side rendered only).
 
 ```js
 /// file: +page.js
@@ -94,7 +94,7 @@ If you add `export const ssr = false` to your root `+layout.js`, your entire app
 
 ### csr
 
-Ordinarily, SvelteKit [hydrates](/docs/appendix#hydration) your server-rendered HTML into an interactive client-side-rendered (CSR) page. Some pages don't require JavaScript at all — many blog posts and 'about' pages fall into this category. In these cases you can disable CSR:
+Ordinarily, SvelteKit [hydrates](/docs/glossary#hydration) your server-rendered HTML into an interactive client-side-rendered (CSR) page. Some pages don't require JavaScript at all — many blog posts and 'about' pages fall into this category. In these cases you can disable CSR:
 
 ```js
 /// file: +page.js

documentation/docs/20-core-concepts/meta.json

@@ -0,0 +1,3 @@
+{
+	"title": "Core concepts"
+}

documentation/docs/30-advanced/meta.json

@@ -0,0 +1,3 @@
+{
+	"title": "Advanced"
+}

documentation/docs/20-accessibility.md → documentation/docs/40-best-practices/10-accessibility.md

@@ -12,7 +12,7 @@ We recognize that accessibility can be hard to get right. If you want to suggest
 
 In traditional server-rendered applications, every navigation (e.g. clicking on an `<a>` tag) triggers a full page reload. When this happens, screen readers and other assistive technology will read out the new page's title so that users understand that the page has changed.
 
-Since navigation between pages in SvelteKit happens without reloading the page (known as [client-side routing](/docs/appendix#routing)), SvelteKit injects a [live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) onto the page that will read out the new page name after each navigation. This determines the page name to announce by inspecting the `<title>` element.
+Since navigation between pages in SvelteKit happens without reloading the page (known as [client-side routing](/docs/glossary#routing)), SvelteKit injects a [live region](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions) onto the page that will read out the new page name after each navigation. This determines the page name to announce by inspecting the `<title>` element.
 
 Because of this behavior, every page in your app should have a unique, descriptive title. In SvelteKit, you can do this by placing a `<svelte:head>` element on each page:
 

documentation/docs/40-best-practices/meta.json

@@ -0,0 +1,3 @@
+{
+	"title": "Best practices"
+}

documentation/docs/50-api-reference/meta.json

@@ -0,0 +1,3 @@
+{
+	"title": "API reference"
+}

documentation/docs/90-additional-resources.md → documentation/docs/60-appendix/20-additional-resources.md

@@ -1,5 +1,5 @@
 ---
-title: Additional Resources
+title: Additional resources
 ---
 
 ### FAQs

documentation/docs/99-appendix.md → documentation/docs/60-appendix/30-glossary.md

@@ -1,5 +1,5 @@
 ---
-title: Appendix
+title: Glossary
 ---
 
 The core of SvelteKit provides a highly configurable rendering engine. This section describes some of the terms used when discussing rendering. A reference for setting these options is provided in the documentation above.

documentation/docs/60-appendix/meta.json

@@ -0,0 +1,3 @@
+{
+	"title": "Appendix"
+}

scripts/check-doc-links.js

@@ -1,18 +1,21 @@
 import fs from 'fs';
 import path from 'path';
+import glob from 'tiny-glob/sync.js';
 import { fileURLToPath } from 'url';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-const doc_filenames = fs.readdirSync(path.join(__dirname, '../documentation/docs'));
-const doc_urls = new Map();
+const cwd = path.join(__dirname, '../documentation/docs');
+
+const doc_filenames = glob('**/*.md', { cwd });
+const doc_urls = new Set();
 
 // 1. collect all doc links and hashes
 
 for (const doc of doc_filenames) {
-	doc_urls.set(doc_name_to_link(doc));
+	doc_urls.add(doc_name_to_link(doc));
 
-	const content = fs.readFileSync(path.join(__dirname, `../documentation/docs/${doc}`), 'utf-8');
+	const content = fs.readFileSync(`${cwd}/${doc}`, 'utf-8');
 
 	const headlines = content.matchAll(/### .+/g);
 	if (!headlines) continue;
@@ -26,7 +29,7 @@ for (const doc of doc_filenames) {
 		} else {
 			last_headline = hash;
 		}
-		doc_urls.set(doc_name_to_link(doc) + '#' + hash);
+		doc_urls.add(doc_name_to_link(doc) + '#' + hash);
 	}
 }
 
@@ -35,7 +38,7 @@ let bad = false;
 // 2. check docs for broken links
 
 for (const doc of doc_filenames) {
-	const content = fs.readFileSync(path.join(__dirname, `../documentation/docs/${doc}`), 'utf-8');
+	const content = fs.readFileSync(`${cwd}/${doc}`, 'utf-8');
 
 	const links = content.match(/\]\(([^)]+)\)/g);
 	if (!links) continue;
@@ -112,7 +115,7 @@ function walk_kit_dir(cwd) {
 }
 
 function doc_name_to_link(file) {
-	return file.replace(/\.md$/, '').replace(/^\d+-/, '');
+	return file.split(path.sep).pop().slice(3, -3);
 }
 
 function slugify(title) {

sites/kit.svelte.dev/package.json

@@ -22,6 +22,7 @@
 		"prismjs": "^1.29.0",
 		"shiki-twoslash": "^3.1.0",
 		"svelte": "^3.48.0",
+		"tiny-glob": "^0.2.9",
 		"typescript": "^4.8.2",
 		"uvu": "^0.5.3",
 		"vite": "^3.1.1",