fix some example docs site issues (#434)
This commit is contained in:
Fred K. Schott
GitHub
parent
40720b2c1e
commit
1437b42038
16 changed files with 206 additions and 102 deletions
5
.changeset/big-ghosts-prove.md
Normal file
5
.changeset/big-ghosts-prove.md
Normal file
|
|
@ -0,0 +1,5 @@
|
|||
---
|
||||
'@astrojs/docs-template': patch
|
||||
---
|
||||
|
||||
Fix issues around sidebar and titles
|
||||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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' },
|
||||
],
|
||||
},
|
||||
];
|
||||
|
|
|
|||
|
|
@ -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 />
|
||||
|
|
|
|||
|
|
@ -1,9 +1,8 @@
|
|||
---
|
||||
title: Markdown Example
|
||||
layout: ../layouts/Main.astro
|
||||
---
|
||||
|
||||
# Markdown example
|
||||
|
||||
This is a fully-featured page, written in Markdown!
|
||||
|
||||
## Section A
|
||||
|
|
|
|||
59
docs-www/src/pages/getting-started.md
Normal file
59
docs-www/src/pages/getting-started.md
Normal file
|
|
@ -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)
|
||||
|
|
@ -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>
|
||||
60
docs-www/src/pages/index.md
Normal file
60
docs-www/src/pages/index.md
Normal file
|
|
@ -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.
|
||||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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' },
|
||||
],
|
||||
},
|
||||
];
|
||||
|
|
|
|||
|
|
@ -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 />
|
||||
|
|
|
|||
|
|
@ -1,9 +1,8 @@
|
|||
---
|
||||
title: Markdown Example
|
||||
layout: ../layouts/Main.astro
|
||||
---
|
||||
|
||||
# Markdown example
|
||||
|
||||
This is a fully-featured page, written in Markdown!
|
||||
|
||||
## Section A
|
||||
|
|
|
|||
|
|
@ -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' },
|
||||
],
|
||||
},
|
||||
];
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
60
examples/docs/src/pages/index.md
Normal file
60
examples/docs/src/pages/index.md
Normal file
|
|
@ -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.
|
||||
Loading…
Reference in a new issue