From b22160e3a8aabe3404f82dbb3bff12dc740b1681 Mon Sep 17 00:00:00 2001
From: Ben McCann <322311+benmccann@users.noreply.github.com>
Date: Sat, 22 May 2021 21:30:06 -0700
Subject: [PATCH] Add appendix docs regarding different rendering methods

---
 documentation/docs/00-introduction.md         |  2 +-
 documentation/docs/11-ssr-and-javascript.md   | 14 ++++----
 ...oubleshooting.md => 90-troubleshooting.md} |  0
 documentation/docs/99-appendix.md             | 33 +++++++++++++++++++
 4 files changed, 41 insertions(+), 8 deletions(-)
 rename documentation/docs/{99-troubleshooting.md => 90-troubleshooting.md} (100%)
 create mode 100644 documentation/docs/99-appendix.md

diff --git a/documentation/docs/00-introduction.md b/documentation/docs/00-introduction.md
index 745324addda7..e82a49813843 100644
--- a/documentation/docs/00-introduction.md
+++ b/documentation/docs/00-introduction.md
@@ -15,7 +15,7 @@ SvelteKit is a framework for building extremely high-performance web apps. You'r
 - 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
 
-Building an app with all the modern best practices — code-splitting, offline support, server-rendered views with client-side hydration — is fiendishly complicated. 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 — code-splitting, [offline support](#service-workers), [server-rendered views](#appendix-ssr) with [client-side hydration](#appendix-hydration) — is fiendishly complicated. SvelteKit does all the boring stuff for you so that you can get on with the creative part.
 
 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 [introductory blog post](https://svelte.dev/blog/svelte-3-rethinking-reactivity) and the [tutorial](https://svelte.dev/tutorial) to learn more.
 
diff --git a/documentation/docs/11-ssr-and-javascript.md b/documentation/docs/11-ssr-and-javascript.md
index 22dbef0210ac..fe9b3e0721a7 100644
--- a/documentation/docs/11-ssr-and-javascript.md
+++ b/documentation/docs/11-ssr-and-javascript.md
@@ -10,9 +10,9 @@ If both are specified, per-page settings override per-app settings in case of co
 
 ### ssr
 
-Disabling server-side rendering effectively turns your SvelteKit app into a **single-page app** or SPA.
+Disabling [server-side rendering](#appendix-ssr) effectively turns your SvelteKit app into a [**single-page app** or SPA](#appendix-csr-and-spa).
 
-> In most situations this is not recommended: it harms SEO, tends to slow down perceived performance, and makes your app inaccessible to users if JavaScript fails or is disabled (which happens [more often than you probably think](https://kryogenix.org/code/browser/everyonehasjs.html)). Sometimes it's appropriate or even necessary, but consider alternatives before disabling SSR.
+> In most situations this is not recommended: see [the discussion in the appendix](#appendix-ssr). Consider whether it's truly appropriate to disable and don't simply disable SSR because you've hit an issue with it.
 
 You can disable SSR app-wide with the [`ssr` config option](#configuration-ssr), or a page-level `ssr` export:
 
@@ -24,9 +24,9 @@ You can disable SSR app-wide with the [`ssr` config option](#configuration-ssr),
 
 ### router
 
-SvelteKit includes a client-side router that intercepts navigations (from the user clicking on links, or interacting with the back/forward buttons) and updates the page contents, rather than letting the browser handle the navigation by reloading.
+SvelteKit includes a [client-side router](#appendix-routing) that intercepts navigations (from the user clicking on links, or interacting with the back/forward buttons) and updates the page contents, rather than letting the browser handle the navigation by reloading.
 
-In certain circumstances you might need to disable this behaviour with the app-wide [`router` config option](#configuration-router) or the page-level `router` export:
+In certain circumstances you might need to disable [client-side routing](#appendix-routing) with the app-wide [`router` config option](#configuration-router) or the page-level `router` export:
 
 ```html
 <script context="module">
@@ -38,7 +38,7 @@ Note that this will disable client-side routing for any navigation from this pag
 
 ### hydrate
 
-Ordinarily, SvelteKit 'hydrates' your server-rendered HTML into an interactive page. Some pages don't require JavaScript at all — many blog posts and 'about' pages fall into this category. In these cases you can skip hydration when the app boots up with the app-wide [`hydrate` config option](#configuration-hydrate) or the page-level `hydrate` export:
+Ordinarily, SvelteKit [hydrates](#appendix-hydration) your server-rendered HTML into an interactive page. Some pages don't require JavaScript at all — many blog posts and 'about' pages fall into this category. In these cases you can skip hydration when the app boots up with the app-wide [`hydrate` config option](#configuration-hydrate) or the page-level `hydrate` export:
 
 ```html
 <script context="module">
@@ -50,7 +50,7 @@ Ordinarily, SvelteKit 'hydrates' your server-rendered HTML into an interactive p
 
 ### prerender
 
-It's likely that at least some pages of your app can be represented as a simple HTML file, since they contain no dynamic or user-specific data. These pages can be _prerendered_ by your [adapter](#adapters), which typically results in better performance and lower costs (since CDNs can make assumptions about static content that they can't make about dynamically server-rendered content, unless your cache headers are expertly configured).
+It's likely that at least some pages of your app can be represented as a simple HTML file generated at build time. These pages can be [_prerendered_](#appendix-prerendering) by your [adapter](#adapters).
 
 If your entire app is suitable for prerendering, you could use [`adapter-static`](https://github.com/sveltejs/kit/tree/master/packages/adapter-static), which will generate HTML files for every page, plus additional files that are requested by `load` functions in those pages.
 
@@ -68,7 +68,7 @@ The prerenderer will start at the root of your app and generate HTML for any pre
 
 The basic rule is this: for a page to be prerenderable, any two users hitting it directly must get the same content from the server.
 
-> In other words, any app that involves user sessions or authentication is _not_ a candidate for `adapter-static`, even if individual pages within an app _are_ suitable for prerendering. You can of course fetch personalized data in `onMount` in a prerendered page, but this may result in a poorer user experience since it will involve blank initial content or loading indicators.
+> Not all pages are suitable for prerendering. Any content that is prerendered will be seen by all users. You can of course fetch personalized data in `onMount` in a prerendered page, but this may result in a poorer user experience since it will involve blank initial content or loading indicators.
 
 Note that you can still prerender pages that load data based on the page's parameters, like our `src/routes/blog/[slug].svelte` example from earlier. The prerenderer will intercept requests made inside `load`, so the data served from `src/routes/blog/[slug].json.js` will also be captured.
 
diff --git a/documentation/docs/99-troubleshooting.md b/documentation/docs/90-troubleshooting.md
similarity index 100%
rename from documentation/docs/99-troubleshooting.md
rename to documentation/docs/90-troubleshooting.md
diff --git a/documentation/docs/99-appendix.md b/documentation/docs/99-appendix.md
new file mode 100644
index 000000000000..1139387dd1bb
--- /dev/null
+++ b/documentation/docs/99-appendix.md
@@ -0,0 +1,33 @@
+---
+title: Appendix
+--- 
+
+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.
+
+### SSR
+
+Server-side rendering (SSR) is the generation of the page contents on the server. SSR is generally preferred for SEO. While some search engines can index content that is dynamically generated on the client-side it may take longer even in these cases. It also tends to improve perceived performance and makes your app accessible to users if JavaScript fails or is disabled (which happens [more often than you probably think](https://kryogenix.org/code/browser/everyonehasjs.html)).
+
+### CSR and SPA
+
+Client-side rendering (CSR) is the generation of the page contents in the web browser using JavaScript. A single-page app (SPA) is an application in which all requests to the server load a single HTML file which then does client-side rendering of the requested contents based on the requested URL. All navigation is handled on the client-side in a process called client-side routing with per-page contents being updated and common layout elements remaining largely unchanged. SPAs do not provide SSR, which has the shortcoming described above. However, some applications are not greatly impacted by these shortcomings such as a complex business application behind a login where SEO would not be important and it is known that users will be accessing the application from a consistent computing environment.
+
+### Prerendering
+
+Prerendering means computing the contents of a page at build time and saving the HTML for display. This approach has the same benefits as traditional server-rendered pages, but avoids recomputing the page for each visitor and so scales nearly for free as the number of visitors increases. The tradeoff is that the build process is more expensive and prerendered content can only be updated by building and deploying a new version of the application.
+
+Not all pages can be prerendered. The basic rule is this: for content to be prerenderable, any two users hitting it directly must get the same content from the server. Note that you can still prerender content that is loaded based on the page's parameters as long as all users will be seeing the same prerendered content.
+
+Pre-rendered pages are not limited to static content. You can build personalized pages if user-specific data is fetched and rendered client-side. This is subject to the caveat that you will experience the downsides of not doing SSR for that content as discussed above.
+
+### SSG
+
+Static Site Generation (SSG) is a term that refers to a site where every page is prerendered. This is what SvelteKit's `adapter-static` does. SvelteKit was not built to do only static site generation like some tools and so may not scale as well to efficiently render a very large number of pages as tools built specifically for that purpose. However, in contrast to most purpose-built SSGs, SvelteKit does nicely allow for mixing and matching different rendering types on different pages. One benefit of fully prerendering a site is that you do not need to maintain or pay for servers to perform SSR. Once generated, the site can be served from CDNs, leading to great "time to first byte" performance. This delivery model is often referred to as JAMstack.
+
+### Hydration
+
+Svelte components store some state and update the DOM when the state is updated. When fetching data during SSR, by default SvelteKit will store this data and transmit it to the client along with the server-rendered HTML. The components can then be initialized on the client with that data without having to call the same API endpoints again. Svelte will then check that the DOM is in the expected state and attach event listeners in a process called hydration. Once the components are fully hydrated, they can react to changes to their properties just like any newly created Svelte component.
+
+### Routing
+
+By default, when you navigate to a new page (by clicking on a link or using the browser's forward or back buttons), SvelteKit will intercept the attempted navigation and handle it instead of allowing the browser to send a request to the server for the destination page. SvelteKit will then update the displayed contents on the client by rendering the component for the new page, which in turn can make calls to the necessary API endpoints. This process of updating the page on the client in response to attempted navigation is called client-side routing.