fix some example docs site issues (#434)

16 files changed, 206 insertions, 102 deletions

diff --git a/.changeset/big-ghosts-prove.md b/.changeset/big-ghosts-prove.md
new file mode 100644
index 000000000..201a14917
--- /dev/null
+++ b/.changeset/big-ghosts-prove.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/docs-template': patch
+---
+
+Fix issues around sidebar and titles
diff --git a/docs-www/src/components/SiteSidebar.astro b/docs-www/src/components/SiteSidebar.astro
index 7279d9aea..0fbad0c83 100644
--- a/docs-www/src/components/SiteSidebar.astro
+++ b/docs-www/src/components/SiteSidebar.astro
@@ -7,10 +7,10 @@ import { sidebar } from '../config.ts';
     {sidebar.map(category => (
       <li>
         <div class="nav-group">
-          <h4 class="nav-group-title">{category.text}</h4>
+          <h4 class="nav-group-title"><a href={`${Astro.site}${category.link}`}>{category.text}</a></h4>
           <ul>
             {category.children.map(child => (
-              <li class="nav-link"><a href={child.link}>{child.text}</a></li>
+              <li class="nav-link"><a href={`${Astro.site}${child.link}`}>{child.text}</a></li>
             ))}
           </ul>
         </div>
diff --git a/docs-www/src/config.ts b/docs-www/src/config.ts
index 113301367..5ec22a02b 100644
--- a/docs-www/src/config.ts
+++ b/docs-www/src/config.ts
@@ -1,12 +1,10 @@
 export const sidebar = [
   {
     text: 'Introduction',
+    link: '', // No leading slash needed, so this links to the homepage
     children: [
-      {
-        text: 'What is Astro?',
-        link: '/',
-      },
-      { text: 'Example', link: '/example' },
+      { text: 'Getting Started', link: 'getting-started' },
+      { text: 'Example', link: 'example' },
     ],
   },
 ];
diff --git a/docs-www/src/layouts/Main.astro b/docs-www/src/layouts/Main.astro
index 37efc2f37..77407918a 100644
--- a/docs-www/src/layouts/Main.astro
+++ b/docs-www/src/layouts/Main.astro
@@ -17,6 +17,9 @@ editHref = `https://github.com/snowpackjs/astro/tree/main/examples/doc/src/pages
     
     <link rel="stylesheet" href="/index.css" />
     <script src="/theme.js" />
+    <link rel="icon" 
+          type="image/svg+xml" 
+          href="/favicon.svg">
 
     <style>
       body {
@@ -195,7 +198,7 @@ editHref = `https://github.com/snowpackjs/astro/tree/main/examples/doc/src/pages
               <svg width="1em" height="1em" viewBox="0 0 340 340" fill="none" xmlns="http://www.w3.org/2000/svg">
                 <path d="M320 170C320 170 296.88 171.746 267.428 188.75C237.975 205.754 205.754 237.975 188.75 267.428C171.746 296.88 170 320 170 320C170 320 168.254 296.88 151.25 267.428C134.246 237.975 102.025 205.754 72.5721 188.75C43.1197 171.746 20 170 20 170C20 170 43.1197 168.254 72.5721 151.25C102.025 134.246 134.246 102.025 151.25 72.5721C168.254 43.1197 170 20 170 20C170 20 171.746 43.1197 188.75 72.5721C205.754 102.025 237.975 134.246 267.428 151.25C296.88 168.254 320 170 320 170Z" fill="currentColor"/>
               </svg>
-              <h1>Astro Docs</h1>
+              <h1>Astroid</h1>
             </a>
           </div>
 
@@ -215,6 +218,7 @@ editHref = `https://github.com/snowpackjs/astro/tree/main/examples/doc/src/pages
       <div id="article">
         <article class="content">
           <main>
+            <h1>{content.title}</h1>
             <slot />
           </main>
           <ArticleFooter />
diff --git a/docs-www/src/pages/example.md b/docs-www/src/pages/example.md
index 0966595d8..4de84789b 100644
--- a/docs-www/src/pages/example.md
+++ b/docs-www/src/pages/example.md
@@ -1,9 +1,8 @@
 ---
+title: Markdown Example
 layout: ../layouts/Main.astro
 ---
 
-# Markdown example
-
 This is a fully-featured page, written in Markdown!
 
 ## Section A
diff --git a/docs-www/src/pages/getting-started.md b/docs-www/src/pages/getting-started.md
new file mode 100644
index 000000000..eb2826dbc
--- /dev/null
+++ b/docs-www/src/pages/getting-started.md
@@ -0,0 +1,59 @@
+---
+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:
+
+- [General Instructions](https://github.com/snowpackjs/astro#readme)
+- [astro.config.mjs](https://github.com/snowpackjs/astro/blob/main/docs/config.md)
+- [API](https://github.com/snowpackjs/astro/blob/main/docs/api.md)
+- [Command Line Interface](https://github.com/snowpackjs/astro/blob/main/docs/cli.md)
+- [Collections](https://github.com/snowpackjs/astro/blob/main/docs/collections.md)
+- [Development Server](https://github.com/snowpackjs/astro/blob/main/docs/dev.md)
+- [Markdown](https://github.com/snowpackjs/astro/blob/main/docs/markdown.md)
+- [Publishing Astro components](https://github.com/snowpackjs/astro/blob/main/docs/publishing.md)
+- [Renderers](https://github.com/snowpackjs/astro/blob/main/docs/renderers.md)
+- [Styling](https://github.com/snowpackjs/astro/blob/main/docs/styling.md)
+- [.astro Syntax](https://github.com/snowpackjs/astro/blob/main/docs/syntax.md)
diff --git a/docs-www/src/pages/guides.md b/docs-www/src/pages/guides.md
deleted file mode 100644
index e69de29bb..000000000
--- a/docs-www/src/pages/guides.md
+++ /dev/null
diff --git a/docs-www/src/pages/index.astro b/docs-www/src/pages/index.astro
deleted file mode 100644
index e4c0a6f8e..000000000
--- a/docs-www/src/pages/index.astro
+++ /dev/null
@@ -1,64 +0,0 @@
----
-import { Markdown } from 'astro/components';
-import Layout from '../layouts/Main.astro';
----
-
-<Layout content={{ title: 'Astro Docs' }}>
-  <Markdown>
-    <img src="https://github.com/snowpackjs/astro/blob/main/assets/social/banner.png?raw=true" alt="Astro" width="638" height="320" >
-
-    ## What is Astro?
-
-    **Astro** is a _fresh but familiar_ approach to building websites. Astro combines decades of proven performance best practices with the DX improvements of the component-oriented era.
-
-    With Astro, you can use your favorite JavaScript framework and automatically ship the bare-minimum amount of JavaScript—by default, it's none at all!
-
-    ## Project Status
-
-    ⚠️ **Astro is still an early beta, missing features and bugs are to be expected!** If you can stomach it, then Astro-built sites are production ready and several production websites built with Astro already exist in the wild. We will update this note once we get closer to a stable, v1.0 release.
-
-    ## 🔧 Quick Start
-
-    > __Important__: Astro is built with [ESM modules](https://nodejs.org/api/esm.html) which are not supported in older version of Node.js. The minimum supported version is __14.16.1__.
-  
-    ```bash
-    # create your project
-    mkdir new-project-directory
-    cd new-project-directory
-    npm init astro
-
-    # install your dependencies
-    npm install
-
-    # start the dev server and open your browser
-    npm start
-    ```  
-
-    ### 🚀 Build & Deployment
-
-    The default Astro project has the following `scripts` in the `/package.json` file:
-
-    ```json
-    {
-      "scripts": {
-        "start": "astro dev",
-        "build": "astro build"
-      }
-    }
-    ```
-
-    For local development, run:
-
-    ```
-    npm run start
-    ```
-
-    To build for production, run the following command:
-
-    ```
-    npm run build
-    ```
-
-    To deploy your Astro site to production, upload the contents of `/dist` to your favorite static site host.
-  </Markdown>
-</Layout>
diff --git a/docs-www/src/pages/index.md b/docs-www/src/pages/index.md
new file mode 100644
index 000000000..f56477902
--- /dev/null
+++ b/docs-www/src/pages/index.md
@@ -0,0 +1,60 @@
+---
+title: Hello, Documentation!
+layout: ../layouts/Main.astro
+---
+
+<img src="https://github.com/snowpackjs/astro/blob/main/assets/social/banner.png?raw=true" alt="Astro" width="638" height="320" >
+
+## What is Astro?
+
+**Astro** is a _fresh but familiar_ approach to building websites. Astro combines decades of proven performance best practices with the DX improvements of the component-oriented era.
+
+With Astro, you can use your favorite JavaScript framework and automatically ship the bare-minimum amount of JavaScript—by default, it's none at all!
+
+## Project Status
+
+⚠️ **Astro is still an early beta, missing features and bugs are to be expected!** If you can stomach it, then Astro-built sites are production ready and several production websites built with Astro already exist in the wild. We will update this note once we get closer to a stable, v1.0 release.
+
+## 🔧 Quick Start
+
+> __Important__: Astro is built with [ESM modules](https://nodejs.org/api/esm.html) which are not supported in older version of Node.js. The minimum supported version is __14.16.1__.
+
+```bash
+# create your project
+mkdir new-project-directory
+cd new-project-directory
+npm init astro
+
+# install your dependencies
+npm install
+
+# start the dev server and open your browser
+npm start
+```  
+
+### 🚀 Build & Deployment
+
+The default Astro project has the following `scripts` in the `/package.json` file:
+
+```json
+{
+  "scripts": {
+    "start": "astro dev",
+    "build": "astro build"
+  }
+}
+```
+
+For local development, run:
+
+```
+npm run start
+```
+
+To build for production, run the following command:
+
+```
+npm run build
+```
+
+To deploy your Astro site to production, upload the contents of `/dist` to your favorite static site host.
diff --git a/examples/docs/src/components/SiteSidebar.astro b/examples/docs/src/components/SiteSidebar.astro
index 30b14621c..0fbad0c83 100644
--- a/examples/docs/src/components/SiteSidebar.astro
+++ b/examples/docs/src/components/SiteSidebar.astro
@@ -7,10 +7,10 @@ import { sidebar } from '../config.ts';
     {sidebar.map(category => (
       <li>
         <div class="nav-group">
-          <h4 class="nav-group-title"><a href={category.link}>{category.text}</a></h4>
+          <h4 class="nav-group-title"><a href={`${Astro.site}${category.link}`}>{category.text}</a></h4>
           <ul>
             {category.children.map(child => (
-              <li class="nav-link"><a href={child.link}>{child.text}</a></li>
+              <li class="nav-link"><a href={`${Astro.site}${child.link}`}>{child.text}</a></li>
             ))}
           </ul>
         </div>
diff --git a/examples/docs/src/config.ts b/examples/docs/src/config.ts
index 4b6268e23..5ec22a02b 100644
--- a/examples/docs/src/config.ts
+++ b/examples/docs/src/config.ts
@@ -1,10 +1,10 @@
 export const sidebar = [
   {
     text: 'Introduction',
-    link: '/',
+    link: '', // No leading slash needed, so this links to the homepage
     children: [
-      { text: 'Getting Started', link: '/getting-started' },
-      { text: 'Example', link: '/example' },
+      { text: 'Getting Started', link: 'getting-started' },
+      { text: 'Example', link: 'example' },
     ],
   },
 ];
diff --git a/examples/docs/src/layouts/Main.astro b/examples/docs/src/layouts/Main.astro
index e6f30faca..77407918a 100644
--- a/examples/docs/src/layouts/Main.astro
+++ b/examples/docs/src/layouts/Main.astro
@@ -218,6 +218,7 @@ editHref = `https://github.com/snowpackjs/astro/tree/main/examples/doc/src/pages
       <div id="article">
         <article class="content">
           <main>
+            <h1>{content.title}</h1>
             <slot />
           </main>
           <ArticleFooter />
diff --git a/examples/docs/src/pages/example.md b/examples/docs/src/pages/example.md
index 0966595d8..4de84789b 100644
--- a/examples/docs/src/pages/example.md
+++ b/examples/docs/src/pages/example.md
@@ -1,9 +1,8 @@
 ---
+title: Markdown Example
 layout: ../layouts/Main.astro
 ---
 
-# Markdown example
-
 This is a fully-featured page, written in Markdown!
 
 ## Section A
diff --git a/examples/docs/src/pages/getting-started.md b/examples/docs/src/pages/getting-started.md
index e034a47ca..eb2826dbc 100644
--- a/examples/docs/src/pages/getting-started.md
+++ b/examples/docs/src/pages/getting-started.md
@@ -1,9 +1,8 @@
 ---
+title: Getting Started
 layout: ../layouts/Main.astro
 ---
 
-# Getting Started
-
 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
@@ -14,10 +13,10 @@ The page navigation, through the side bar on the left, needs to be manually upda
 export const sidebar = [
   {
     text: 'Introduction',
-    link: '/',
+    link: '', // No leading slash needed, so this links to the homepage
     children: [
-      { text: 'Getting Started', link: '/getting-started' },
-      { text: 'Example', link: '/example' },
+      { text: 'Getting Started', link: 'getting-started' },
+      { text: 'Example', link: 'example' },
     ],
   },
 ];
diff --git a/examples/docs/src/pages/index.astro b/examples/docs/src/pages/index.astro
deleted file mode 100644
index 6cba4c7fe..000000000
--- a/examples/docs/src/pages/index.astro
+++ /dev/null
@@ -1,16 +0,0 @@
----
-import { Markdown } from 'astro/components';
-import Layout from '../layouts/Main.astro';
----
-
-<Layout content={{ title: 'Hello world!' }}>
-  <Markdown>
-    # Hello world!
-
-    This is a starter template, have fun building your next documentation site with [Astro](https://astro.build).
-
-    It offers the right mix of simple-to-use [Markdown pages](/example) and rich, interactive components embedded in `.astro` files using `<Markdown>`.
-
-    The docs template has some nice components, for more information click [here](/getting-started).
-  </Markdown>
-</Layout>
diff --git a/examples/docs/src/pages/index.md b/examples/docs/src/pages/index.md
new file mode 100644
index 000000000..f56477902
--- /dev/null
+++ b/examples/docs/src/pages/index.md
@@ -0,0 +1,60 @@
+---
+title: Hello, Documentation!
+layout: ../layouts/Main.astro
+---
+
+<img src="https://github.com/snowpackjs/astro/blob/main/assets/social/banner.png?raw=true" alt="Astro" width="638" height="320" >
+
+## What is Astro?
+
+**Astro** is a _fresh but familiar_ approach to building websites. Astro combines decades of proven performance best practices with the DX improvements of the component-oriented era.
+
+With Astro, you can use your favorite JavaScript framework and automatically ship the bare-minimum amount of JavaScript—by default, it's none at all!
+
+## Project Status
+
+⚠️ **Astro is still an early beta, missing features and bugs are to be expected!** If you can stomach it, then Astro-built sites are production ready and several production websites built with Astro already exist in the wild. We will update this note once we get closer to a stable, v1.0 release.
+
+## 🔧 Quick Start
+
+> __Important__: Astro is built with [ESM modules](https://nodejs.org/api/esm.html) which are not supported in older version of Node.js. The minimum supported version is __14.16.1__.
+
+```bash
+# create your project
+mkdir new-project-directory
+cd new-project-directory
+npm init astro
+
+# install your dependencies
+npm install
+
+# start the dev server and open your browser
+npm start
+```  
+
+### 🚀 Build & Deployment
+
+The default Astro project has the following `scripts` in the `/package.json` file:
+
+```json
+{
+  "scripts": {
+    "start": "astro dev",
+    "build": "astro build"
+  }
+}
+```
+
+For local development, run:
+
+```
+npm run start
+```
+
+To build for production, run the following command:
+
+```
+npm run build
+```
+
+To deploy your Astro site to production, upload the contents of `/dist` to your favorite static site host.