6 files changed, 225 insertions, 62 deletions
diff --git a/examples/docs/src/pages/example.md b/examples/docs/src/pages/en/example.md
index 4de84789b..a5deeaff9 100644
--- a/examples/docs/src/pages/example.md
+++ b/examples/docs/src/pages/en/example.md
@@ -1,6 +1,6 @@
 ---
 title: Markdown Example
-layout: ../layouts/Main.astro
+layout: ~/layouts/MainLayout.astro
 ---
 
 This is a fully-featured page, written in Markdown!
@@ -17,7 +17,9 @@ Nam quam dolor, pellentesque sed odio euismod, feugiat tempus tellus. Quisque ar
 
 ```markdown
 ---
-layout: ../layouts/Main.astro
+title: Markdown Page!
+lang: en
+layout: ~/layouts/MainLayout.astro
 ---
 
 # Markdown example
diff --git a/examples/docs/src/pages/en/getting-started.md b/examples/docs/src/pages/en/getting-started.md
new file mode 100644
index 000000000..33494432c
--- /dev/null
+++ b/examples/docs/src/pages/en/getting-started.md
@@ -0,0 +1,190 @@
+---
+title: Getting Started
+layout: ~/layouts/MainLayout.astro
+---
+
+This template already provides your pages with a side bar navigation (on the left) for your pages, and a content navigation (on the right) for your sections.
+
+## Page navigation
+
+The page navigation, through the side bar on the left, needs to be manually updated. Open the `config.ts` file and you will find the following structure:
+
+```ts
+export const SIDEBAR = {
+  en: [
+    { text: 'Getting Started', header: true },
+    { text: 'Introduction', link: 'en/introduction' },
+    { text: 'Getting Started', link: 'en/getting-started' },
+    { text: 'Example', link: 'en/example' },
+  ],
+  es: [
+    { text: 'Empezando', header: true },
+    { text: 'Introducción', link: 'es/introduction' },
+    { text: 'Empezando', link: 'es/getting-started' },
+    { text: 'Ejemplo', link: 'es/example' },
+  ],
+  fr: [
+    { text: 'Commencer', header: true },
+    { text: 'Introduction', link: 'fr/introduction' },
+    { text: 'Commencer', link: 'fr/getting-started' },
+    { text: 'Exemple', link: 'fr/example' },
+  ],
+};
+```
+
+The sidebar supports many languages, and each language has items to display, and pages to link to, allowing for a truly native experience for international users. You can change this file to match the pages you want to display, the object with the `{ header: true, ... }` set to true will act as a section title and cannot contain a link.
+
+The page navigation is generated in the `src/components/LeftSidebar/LeftSidebar.astro`, so if you want to change the depth of elements displayed, styles, etc, that's the place to go.
+
+## Section navigation
+
+The section navigation, through the side bar on the right, is automatically generated by the `src/components/RightSidebar/RightSidebar.astro` file, it uses the meta-data from markdown files to generate the structure you see.
+
+By default only elements from depth 2 to 5 will be displayed, and at the moment doesn't work for `.astro files`.
+
+## Other Components
+
+### Footer
+
+You can edit your footer here `src/components/Footer/Footer.astro`, at the moment it is composed of a list of avatars. You can generate your own avatar [here](https://getavataaars.com/) and replace the ones from `src/components/Footer/AvatarList.astro`.
+
+### Theme
+
+The `src/components/RightSidebar/ThemeToggleButton.tsx` is only responsible for applying the theme, to change the theme colors see `public/theme.css`
+
+## Multiple Languages
+
+By default the Astro docs template encourages writing your docs in mutliple languages, it also encourages writing your docs in a specific file structure
+
+```
+📦pages
+ ┣ 📂en
+ ┃ ┣ 📜example.md
+ ┃ ┣ 📜getting-started.md
+ ┃ ┣ 📜index.astro
+ ┃ ┗ 📜introduction.md
+ ┣ 📂es
+ ┃ ┣ 📜example.md
+ ┃ ┣ 📜getting-started.md
+ ┃ ┣ 📜index.astro
+ ┃ ┗ 📜introduction.md
+ ┣ 📂fr
+ ┃ ┣ 📜example.md
+ ┃ ┣ 📜getting-started.md
+ ┃ ┣ 📜index.astro
+ ┃ ┗ 📜introduction.md
+ ┗ 📜index.astro
+```
+
+each folder within the `pages/` folder represents a language, to add new languages, you will need to create a new langauge folder,
+add the langauges name to the `LANGUAGE_NAMES` variable in the [`languages.ts`](../../languages.ts) file, and add new sidebar links corrosponding to the new language. E.g. Adding Deutsch as a supported language
+
+1. Create the `de/` folder in the pages directory
+
+```
+📦pages
+ ┣ 📂en
+ ┃ ┣ 📜example.md
+ ┃ ┣ 📜getting-started.md
+ ┃ ┣ 📜index.astro
+ ┃ ┗ 📜introduction.md
+ ┣ 📂de
+ ┃ ┣ 📜example.md
+ ┃ ┣ 📜getting-started.md
+ ┃ ┣ 📜index.astro
+ ┃ ┗ 📜introduction.md
+ ┗ 📜index.astro
+```
+
+2. Add Deutsch to the `LANGUAGE_NAMES` variable in the [`languages.ts`](../../languages.ts) file
+
+```ts
+// src/languages.ts
+export const LANGUAGE_NAMES = {
+  English: 'en',
+  Deutsch: 'de',
+};
+
+// ...
+```
+
+3. Add Deutch as a localized language for the SIDEBAR
+
+```ts
+// src/config.ts
+export const SIDEBAR = {
+  en: [
+    { text: 'Getting Started', header: true },
+    { text: 'Introduction', link: 'en/introduction' },
+    { text: 'Getting Started', link: 'en/getting-started' },
+    { text: 'Example', link: 'en/example' },
+  ],
+  de: [
+    { text: 'Einstieg', header: true },
+    { text: 'Einführung', link: 'de/introduction' },
+    { text: 'Einstieg', link: 'de/getting-started' },
+    { text: 'Beispiel', link: 'de/example' },
+  ],
+};
+
+// ...
+```
+
+> _**Note**: make sure the sidebar links point to the proper language folder_
+
+<!-- , but if you are unable to properly support multiple languages, you can disable multiple languages, you set the `DISABLE_MULTIPLE_LANGUAGES` variable in the [`config.ts`](../../config.ts) file to `true`, but you still need to change and tweak a couple more things.
+
+After settings `DISABLE_MULTIPLE_LANGUAGES` you can now move the pages from the language folder you wish to use, e.g. I speak english, so, I would delete every other folders and files in the [`pages/`](../) folder except for the [`en/`](./) folder, I would then move the files from the [`en/`](./) folder to the [`pages/`](../) folder, delete all `index.astro` files, and finally delete the [`en/`](./) folder.
+
+The file structure will look like this once you are done,
+
+```
+📦src
+ ┣ 📂components
+ ┃ ┣ ...
+ ┣ 📂layouts
+ ┃ ┗ 📜MainLayout.astro
+ ┣ 📂pages
+ ┃ ┣ 📜example.md
+ ┃ ┣ 📜getting-started.md
+ ┃ ┗ 📜introduction.md
+ ┣ 📜config.ts
+ ┗ 📜languages.ts
+```
+
+You will then need to rename `introductions.md` to `index.md`, and reorganize the `SIDEBAR` variable in the [`config.ts`](../../config.ts) file to resemble something like this (remember to change the links, since the `en/` folder has been deleted),
+
+```ts
+export const SIDEBAR = [
+  // index.md is the homepage, so, you don't need to set a sidebar link
+  { text: 'Introduction', header: true },
+  { text: 'Getting Started', link: 'getting-started' },
+  { text: 'Example', link: 'example' },
+]
+```
+
+and that's it. -->
+
+## Algolia DocSearch
+
+[Algolia](https://www.algolia.com/) offers [DocSearch](https://docsearch.algolia.com/), a _"State-of-the-art search for technical documentation"_. We use DocSearch for the Astro docs as it's a great documentation search engine, to make things setting up docs easier we built it into the docs template, you can setup DocSearch for your site by following these instructions, ...
+
+### 🛠 Configuration
+
+...
+
+## Documentation
+
+For more information on how to use Astro components, check the documentation pages:
+
+- [Quick Start](https://docs.astro.build/quick-start)
+- [astro.config.mjs](https://docs.astro.build/reference/configuration-reference)
+- [API](https://docs.astro.build/reference/api-reference)
+- [Command Line Interface](https://docs.astro.build/reference/cli-reference)
+- [Collections](https://docs.astro.build/core-concepts/collections)
+- [Development Server](https://docs.astro.build/reference/dev/)
+- [Markdown](https://docs.astro.build/guides/markdown-content)
+- [Publishing Astro components](https://docs.astro.build/guides/publish-to-npm)
+- [Renderers](https://docs.astro.build/reference/renderer-reference)
+- [Styling](https://docs.astro.build/guides/styling)
+- [.astro Syntax](https://docs.astro.build/core-concepts/astro-components)
diff --git a/examples/docs/src/pages/en/index.astro b/examples/docs/src/pages/en/index.astro
new file mode 100644
index 000000000..5731a3976
--- /dev/null
+++ b/examples/docs/src/pages/en/index.astro
@@ -0,0 +1,5 @@
+---
+import REDIRECT from "../index.astro";
+---
+
+<REDIRECT />
+\ No newline at end of file
diff --git a/examples/docs/src/pages/index.md b/examples/docs/src/pages/en/introduction.md
index cd5ce6454..7b3142f71 100644
--- a/examples/docs/src/pages/index.md
+++ b/examples/docs/src/pages/en/introduction.md
@@ -1,6 +1,6 @@
 ---
 title: Hello, Documentation!
-layout: ../layouts/Main.astro
+layout: ~/layouts/MainLayout.astro
 ---
 
 <img src="https://github.com/snowpackjs/astro/blob/main/assets/social/banner.png?raw=true" alt="Astro" width="638" height="320" >
@@ -39,6 +39,7 @@ The default Astro project has the following `scripts` in the `/package.json` fil
 ```json
 {
   "scripts": {
+    "start": "astro dev",
     "dev": "astro dev",
     "build": "astro build",
     "preview": "astro preview"
diff --git a/examples/docs/src/pages/getting-started.md b/examples/docs/src/pages/getting-started.md
deleted file mode 100644
index ab9c79617..000000000
--- a/examples/docs/src/pages/getting-started.md
+++ /dev/null
@@ -1,59 +0,0 @@
----
-title: Getting Started
-layout: ../layouts/Main.astro
----
-
-This template already provides your pages with a side bar navigation (on the left) for your pages, and a content navigation (on the right) for your sections.
-
-## Page navigation
-
-The page navigation, through the side bar on the left, needs to be manually updated. Open the `config.ts` file and you will find the following structure:
-
-```ts
-export const sidebar = [
-  {
-    text: 'Introduction',
-    link: '', // No leading slash needed, so this links to the homepage
-    children: [
-      { text: 'Getting Started', link: 'getting-started' },
-      { text: 'Example', link: 'example' },
-    ],
-  },
-];
-```
-
-You can change this file to match the pages you want to display, the items within `children` can also have children elements, but only the first level and second levels will be displayed.
-
-The page navigation is generated in the `src/components/SiteSidebar.astro`, so if you want to change the depth of elements displayed, styles, etc, that's the place to go.
-
-## Section navigation
-
-The section navigation, through the side bar on the right, is automatically generated by the `src/components/DocSidebar.tsx` file, it uses the meta-data from markdown files to generate the structure you see.
-
-By default only elements from depth 2 to 5 will be displayed, and at the moment doesn't work for `.astro files`.
-
-## Other Components
-
-### Footer
-
-You can edit your footer here `src/components/ArticleFooter.astro`, at the moment it is composed of a list of avatars. You can generate your own avatar [here](https://getavataaars.com/) and replace the ones from `AvatarList.astro`.
-
-### Theme
-
-The `src/components/ThemeToggle.tsx` is only responsible for applying the theme, to change the theme colors see `public/theme.css`
-
-## Documentation
-
-For more information on how to use Astro components, check the documentation pages:
-
-- [Quick Start](https://docs.astro.build/quick-start)
-- [astro.config.mjs](https://docs.astro.build/reference/configuration-reference)
-- [API](https://docs.astro.build/reference/api-reference)
-- [Command Line Interface](https://docs.astro.build/reference/cli-reference)
-- [Collections](https://docs.astro.build/core-concepts/collections)
-- [Development Server](https://docs.astro.build/reference/dev/)
-- [Markdown](https://docs.astro.build/guides/markdown-content)
-- [Publishing Astro components](https://docs.astro.build/guides/publish-to-npm)
-- [Renderers](https://docs.astro.build/reference/renderer-reference)
-- [Styling](https://docs.astro.build/guides/styling)
-- [.astro Syntax](https://docs.astro.build/core-concepts/astro-components)
diff --git a/examples/docs/src/pages/index.astro b/examples/docs/src/pages/index.astro
new file mode 100644
index 000000000..f5a8fd318
--- /dev/null
+++ b/examples/docs/src/pages/index.astro
@@ -0,0 +1,24 @@
+---
+import Layout from '../layouts/MainLayout.astro';
+import { KNOWN_LANGUAGES } from "../languages";
+---
+<div id="known_languages" hidden>{KNOWN_LANGUAGES.join(",")}</div>
+<script>
+  // WIP: trigger a client-side redirect based on the browser language.
+  // A vercel.json redirect is enforced in production, so no user should ever see this page.
+  // Remove the vercel.json redirect when this is ready.
+  const KNOWN_LANGUAGES = document.querySelector("#known_languages")?.textContent?.split(",") ?? ['bg', 'de','en','es','fi','nl','pt-br','zh-CN','zh-TW', 'fr'];
+  let newLangWithRegion = (window.navigator.userLanguage || window.navigator.language || 'en-US').substr(0, 5);
+  let newLang = newLangWithRegion.substr(0, 2);
+
+  let langPathRegex = new RegExp(`\/(${KNOWN_LANGUAGES.join("|")})\/`);
+  let actualDest = window.location.pathname.replace(langPathRegex, "/");
+  if (actualDest == "/") actualDest = `/introduction`;
+  if (KNOWN_LANGUAGES.includes(newLangWithRegion)) {
+    window.location.pathname = '/' + newLangWithRegion + actualDest;
+  } else if (KNOWN_LANGUAGES.includes(newLang)) {
+    window.location.pathname = '/' + newLang + actualDest;
+  } else {
+    window.location.pathname = actualDest;
+  }
+</script>