michael/astro
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

example: update doc template

Browse source
This commit is contained in:
Nate Moore 2021-05-21 13:15:49 -05:00
parent 405fe86f85
commit a2dca4675d
15 changed files with 389 additions and 425 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

198
examples/astro-markdown/src/pages/collections.astro
View file

@ -9,203 +9,7 @@ import Markdown from 'astro/components/Markdown.astro';
<body>
<main>
<Markdown>
# 🍱 Collections
## ❓ What are Collections?
[Fetching data is easy in Astro][docs-data]. But what if you wanted to make a paginated blog? What if you wanted an easy way to sort data, or filter data based on part of the URL? Or generate an RSS 2.0 feed? When you need something a little more powerful than simple data fetching, Astro’s Collections API may be what you need.
An Astro Collection is similar to the general concept of Collections in static site generators like Jekyll, Hugo, Eleventy, etc. It’s a general way to load an entire data set. But one big difference between Astro Collections and traditional static site generators is: **Astro lets you seamlessly blend remote API data and local files in a JAMstack-friendly way.** To see how, this guide will walk through a few examples. If you’d like, you can reference the [blog example project][example-blog] to see the finished code in context.
## 🧑‍🎨 How to Use
By default, any Astro component can fetch data from any API or local `*.md` files. But what if you had a blog you wanted to paginate? What if you wanted to generate dynamic URLs based on metadata (e.g. `/tag/:tag/`)? Or do both together? Astro Collections are a way to do all of that. It’s perfect for generating blog-like content, or scaffolding out dynamic URLs from your data.
Let’s pretend we have some blog posts written already. This is our starting project structure:
```
└── src/
└── pages/
└── post/
└── (blog content)
```
The first step in adding some dynamic collections is deciding on a URL schema. For our example website, we’re aiming for the following URLs:
- `/post/:post`: A single blog post page
- `/posts/:page`: A list page of all blog posts, paginated, and sorted most recent first
- `/tag/:tag`: All blog posts, filtered by a specific tag
Because `/post/:post` references the static files we have already, that doesn’t need to be a collection. But we will need collections for `/posts/:page` and `/tag/:tag` because those will be dynamically generated. For both collections we’ll create a `/src/pages/$[collection].astro` file. This is our new structure:
```diff
└── src/
└── pages/
├── post/
│ └── (blog content)
+ ├── $posts.astro -> /posts/1, /posts/2, …
+ └── $tag.astro -> /tag/:tag/1, /tag/:tag/2, …
```
💁‍ **Tip**: Any `.astro` filename beginning with a `$` is how it’s marked as a collection.
In each `$[collection].astro` file, we’ll need 2 things:
```js
// 1. We need to mark “collection” as a prop (this is a special reserved name)
export let collection: any;
// 2. We need to export an async createCollection() function that will retrieve our data.
export async function createCollection() {
return {
async data() {
// return data here to load (we’ll cover how later)
},
};
}
```
These are important so your data is exposed to the page as a prop, and also Astro has everything it needs to gather your data and generate the proper routes. How it does this is more clear if we walk through a practical example.
#### Example 1: Simple pagination
Our blog posts all contain `title`, `tags`, and `published_at` in their frontmatter:
```md
---
title: My Blog Post
tags:
- javascript
published_at: 2021-03-01 09:34:00
---
# My Blog post
…
```
There’s nothing special or reserved about any of these names; you’re free to name everything whatever you’d like, or have as much or little frontmatter as you need.
```jsx
// /src/pages/$posts.astro
---
export let collection: any;
export async function createCollection() {
const allPosts = Astro.fetchContent('./post/*.md'); // load data that already lives at `/post/:slug`
allPosts.sort((a, b) => new Date(b.published_at) - new Date(a.published_at)); // sort newest -> oldest (we got "published_at" from frontmatter!)
// (load more data here, if needed)
return {
async data() {
return allPosts;
},
pageSize: 10, // how many we want to show per-page (default: 25)
};
}
function formatDate(date) {
return new Date(date).toUTCString();
}
---
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Blog Posts: page {collection.page.current}</title>
<link rel="canonical" href={collection.url.current} />
<link rel="prev" href={collection.url.prev} />
<link rel="next" href={collection.url.next} />
</head>
<body>
<main>
<h5>Results {collection.start + 1}–{collection.end + 1} of {collection.total}</h6>
{collection.data.map((post) => (
<h1>{post.title}</h1>
<time>{formatDate(post.published_at)}</time>
<a href={post.url}>Read</a>
)}
</main>
<footer>
<h4>Page {collection.page.current} / {collection.page.last}</h4>
<nav class="nav">
<a class="prev" href={collection.url.prev || '#'}>Prev</a>
<a class="next" href={collection.url.next || '#'}>Next</a>
</nav>
</footer>
</body>
</html>
```
Let’s walk through some of the key parts:
- `export let collection`: this is important because it exposes a prop to the page for Astro to return with all your data loaded. ⚠️ **It must be named `collection`**.
- `export async function createCollection()`: this is also required, **and must be named this exactly.** This is an async function that lets you load data from anywhere (even a remote API!). At the end, you must return an object with `{ data: yourData }`. There are other options such as `pageSize` we’ll cover later.
- `{collection.data.map((post) => (…`: this lets us iterate over all the markdown posts. This will take the shape of whatever you loaded in `createCollection()`. It will always be an array.
- `{collection.page.current}`: this, and other properties, simply return more info such as what page a user is on, what the URL is, etc. etc.
- Curious about everything on `collection`? See the [reference][collection-api].
#### Example 2: Advanced filtering & pagination
In our earlier example, we covered simple pagination for `/posts/1`, but we’d still like to make `/tag/:tag/1` and `/year/:year/1`. To do that, we’ll create 2 more collections: `/src/pages/$tag.astro` and `src/pages/$year.astro`. Assume that the markup is the same, but we’ve expanded the `createCollection()` function with more data.
```diff
// /src/pages/$tag.astro
---
import Pagination from '../components/Pagination.astro';
import PostPreview from '../components/PostPreview.astro';
export let collection: any;
export async function createCollection() {
const allPosts = Astro.fetchContent('./post/*.md');
allPosts.sort((a, b) => new Date(b.published_at) - new Date(a.published_at));
+ const allTags = [...new Set(allPosts.map((post) => post.tags).flat())]; // gather all unique tags (we got "tags" from frontmatter!)
+ allTags.sort((a, b) => a.localeCompare(b)); // sort tags A -> Z
+ const routes = allTags.map((tag) => ({ tag })); // this is where we set { params: { tag } }
return {
- async data() {
- return allPosts;
+ async data({ params }) {
+ return allPosts.filter((post) => post.tags.includes(params.tag)); // filter posts that match the :tag from the URL ("params")
},
pageSize: 10,
+ routes,
+ permalink: ({ params }) => `/tag/${params.tag}/` // this is where we generate our URL structure
};
}
---
```
Some important concepts here:
- `routes = allTags.map((tag) => ({ tag }))`: Astro handles pagination for you automatically. But when it needs to generate multiple routes, this is where you tell Astro about all the possible routes. This way, when you run `astro build`, your static build isn’t missing any pages.
- `` permalink: ({ params }) => `/tag/${params.tag}/` ``: this is where you tell Astro what the generated URL should be. Note that while you have control over this, the root of this must match the filename (it's best **NOT** to use `/pages/$tag.astro` to generate `/year/$year.astro`; that should live at `/pages/$year.astro` as a separate file).
- `allPosts.filter((post) => post.tag === params.tag)`: we aren’t returning all posts here; we’re only returning posts with a matching tag. _What tag,_ you ask? The `routes` array has `[{ tag: 'javascript' }, { tag: '…`, and all the routes we need to gather. So we first need to query everything, but only return the `.filter()`ed posts at the very end.
Other things of note is that we are sorting like before, but we filter by the frontmatter `tag` property, and return those at URLs.
These are still paginated, too! But since there are other conditions applied, they live at a different URL.
#### Tips
- Having to load different collections in different `$[collection].astro` files might seem like a pain at first, until you remember **you can create reusable components!** Treat `/pages/*.astro` files as your one-off routing & data fetching logic, and treat `/components/*.astro` as your reusable markup. If you find yourself duplicating things too much, you can probably use a component instead!
- Stay true to `/pages/$[collection].astro` naming. If you have an `/all-posts/*` route, then use `/pages/$all-posts.astro` to manage that. Don’t try and trick `permalink` to generate too many URL trees; it’ll only result in pages being missed when it comes time to build.
### 📚 Further Reading
- [Fetching data in Astro][docs-data]
- API Reference: [collection][collection-api]
- API Reference: [createCollection()][create-collection-api]
- API Reference: [Creating an RSS feed][create-collection-api]
[docs-data]: ../README.md#-fetching-data
[collection-api]: ./api.md#collection
[create-collection-api]: ./api.md#createcollection
[example-blog]: ../examples/blog
[fetch-content]: ./api.md#fetchcontent
</Markdown>
</Markdown>
</main>
</body>
</html>

2
examples/astro-markdown/src/pages/index.astro
View file

@ -17,7 +17,7 @@ const items = ['A', 'B', 'C'];
**Astro Markdown** brings native Markdown support to HTML!
> It's inspired by [`mdx`](https://mdxjs.com/) and powered by [`remark`](https://github.com/remarkjs/remark)).
> It's inspired by [`mdx`](https://mdxjs.com/) and powered by [`remark`](https://github.com/remarkjs/remark).
The best part? It comes with all the Astro features you expect.

155
examples/doc/public/code.css Normal file
View file

@ -0,0 +1,155 @@
.language-css > code,
.language-sass > code,
.language-scss > code {
color: #fd9170;
}
[class*="language-"] .namespace {
opacity: 0.7;
}
.token.atrule {
color: #c792ea;
}
.token.attr-name {
color: #ffcb6b;
}
.token.attr-value {
color: #a5e844;
}
.token.attribute {
color: #a5e844;
}
.token.boolean {
color: #c792ea;
}
.token.builtin {
color: #ffcb6b;
}
.token.cdata {
color: #80cbc4;
}
.token.char {
color: #80cbc4;
}
.token.class {
color: #ffcb6b;
}
.token.class-name {
color: #f2ff00;
}
.token.comment {
color: #616161;
}
.token.constant {
color: #c792ea;
}
.token.deleted {
color: #ff6666;
}
.token.doctype {
color: #616161;
}
.token.entity {
color: #ff6666;
}
.token.function {
color: #c792ea;
}
.token.hexcode {
color: #f2ff00;
}
.token.id {
color: #c792ea;
font-weight: bold;
}
.token.important {
color: #c792ea;
font-weight: bold;
}
.token.inserted {
color: #80cbc4;
}
.token.keyword {
color: #c792ea;
}
.token.number {
color: #fd9170;
}
.token.operator {
color: #89ddff;
}
.token.prolog {
color: #616161;
}
.token.property {
color: #80cbc4;
}
.token.pseudo-class {
color: #a5e844;
}
.token.pseudo-element {
color: #a5e844;
}
.token.punctuation {
color: #89ddff;
}
.token.regex {
color: #f2ff00;
}
.token.selector {
color: #ff6666;
}
.token.string {
color: #a5e844;
}
.token.symbol {
color: #c792ea;
}
.token.tag {
color: #ff6666;
}
.token.unit {
color: #fd9170;
}
.token.url {
color: #ff6666;
}
.token.variable {
color: #ff6666;
}

120
examples/doc/public/index.css
View file

@ -1,4 +1,5 @@
@import './theme';
@import './code';
* {
box-sizing: border-box;
@ -83,6 +84,9 @@ a {
font-weight: 400;
text-underline-offset: 0.08em;
text-decoration: none;
display: inline-flex;
align-items: center;
gap: 0.5rem;
}
a > code:not([class*="language"]) {
@ -149,36 +153,22 @@ pre {
background-color: var(--theme-code-bg);
color: var(--theme-code-text);
--padding-block: 1rem;
--padding-inline: 1.25rem;
--padding-inline: 2rem;
padding: var(--padding-block) var(--padding-inline);
padding-right: calc(var(--padding-inline) * 2);
margin-left: calc(var(--padding-inline) * -1);
margin-right: calc(var(--padding-inline) * -1);
margin-left: calc(50vw - var(--padding-inline));
transform: translateX(-50vw);
line-height: 1.414;
width: calc(100vw + 4px);
max-width: calc(100% + (var(--padding-inline) * 2));
overflow-y: hidden;
overflow-x: auto;
max-width: 100vw;
}
pre::before,
pre::after {
position: absolute;
content: '';
display: block;
pointer-events: none;
top: 0;
bottom: 0;
height: 100%;
width: var(--padding-inline);
background: red;
}
pre::before {
left: 0;
}
pre::after {
right: 0;
}
@media (min-width: 37.75em) {
pre {
--padding-inline: 1.25rem;
border-radius: 8px;
}
}
@ -272,3 +262,89 @@ input[name="theme-toggle"] {
left: 0;
z-index: -1;
}
nav h4 {
font-weight: 400;
font-size: 1.25rem;
margin: 0;
margin-bottom: 1em;
}
.edit-on-github,
.header-link {
font-size: 1rem;
padding-left: 1rem;
border-left: 4px solid var(--theme-divider);
}
.edit-on-github:hover,
.edit-on-github:focus,
.header-link:hover,
.header-link:focus {
color: var(--theme-text-light);
border-left-color: var(--theme-text-lighter);
}
.header-link:focus-within {
color: var(--theme-text-light);
border-left-color: var(--theme-text-lighter);
}
.header-link.active {
border-left-color: var(--theme-accent);
color: var(--theme-accent);
}
.header-link.depth-2 {
font-weight: 600;
}
.header-link.depth-3 {
padding-left: 2rem;
}
.header-link.depth-4 {
padding-left: 3rem;
}
.edit-on-github,
.header-link a {
font: inherit;
color: inherit;
text-decoration: none;
}
.edit-on-github {
margin-top: 2rem;
text-decoration: none;
}
.edit-on-github > * {
text-decoration: none;
}
.nav-link {
font-size: 1rem;
margin-bottom: 0;
transform: translateX(0);
transition: 120ms transform ease-out;
}
.nav-link:hover,
.nav-link:focus {
color: var(--theme-text-lighter);
transform: translateX(0.25em);
}
.nav-link:focus-within {
color: var(--theme-text-lighter);
transform: translateX(0.25em);
}
.nav-link a {
font: inherit;
color: inherit;
text-decoration: none;
}
.nav-groups > li + li {
margin-top: 2rem;
}

10
examples/doc/src/components/CodeBlock.tsx
View file

@ -1,10 +0,0 @@
import type { FunctionalComponent } from 'preact';
import { h, Fragment } from 'preact';
const CodeBlock: FunctionalComponent = ({ children }) => {
return <div className="code-block">
{children}
</div>
}
export default CodeBlock;

13
examples/doc/src/components/DocSidebar.astro
View file

@ -1,13 +0,0 @@
---
import EditOnGithub from './EditOnGithub.astro';
---
<nav>
<ul>
<li>Contents</li>
</ul>
<ul>
<li><EditOnGithub /></li>
</ul>
</nav>

55
examples/doc/src/components/DocSidebar.tsx Normal file
View file

@ -0,0 +1,55 @@
import type { FunctionalComponent } from 'preact';
import { h } from 'preact';
import { useState, useEffect, useRef } from 'preact/hooks';
import EditOnGithub from './EditOnGithub';
const DocSidebar: FunctionalComponent<{ headers: any[]; editHref: string; }> = ({ headers, editHref }) => {
const itemOffsets = useRef([]);
const [activeId, setActiveId] = useState<string>(undefined);
useEffect(() => {
const getItemOffsets = () => {
const titles = document.querySelectorAll('article :is(h2, h3, h4)');
itemOffsets.current = Array.from(titles).map(title => ({
id: title.id,
topOffset: title.getBoundingClientRect().top + window.scrollY
}));
}
const onScroll = () => {
const itemIndex = itemOffsets.current.findIndex(item => item.topOffset > window.scrollY + (window.innerHeight / 3));
if (itemIndex === 0) {
setActiveId(undefined);
} else if (itemIndex === -1) {
setActiveId(itemOffsets.current[itemOffsets.current.length - 1].id)
} else {
setActiveId(itemOffsets.current[itemIndex - 1].id)
}
}
getItemOffsets();
window.addEventListener('resize', getItemOffsets);
window.addEventListener('scroll', onScroll);
return () => {
window.removeEventListener('resize', getItemOffsets);
window.removeEventListener('scroll', onScroll);
}
}, []);
return (
<nav>
<div>
<h4>Contents</h4>
<ul>
{headers.filter(({ depth }) => depth > 1 && depth < 5).map(header => <li class={`header-link depth-${header.depth} ${activeId === header.slug ? 'active' : ''}`.trim()}><a href={`#${header.slug}`}>{header.text}</a></li>)}
</ul>
</div>
<div>
<EditOnGithub href={editHref} />
</div>
</nav>
);
}
export default DocSidebar;

16
examples/doc/src/components/EditOnGithub.astro
View file

@ -1,16 +0,0 @@
---
export let href: string;
---
<a href={href}>
<svg preserveAspectRatio="xMidYMid meet" height="1em" width="1em" fill="currentColor" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 438.549 438.549" stroke="none" class="icon-7f6730be--text-3f89f380"><g><path d="M409.132 114.573c-19.608-33.596-46.205-60.194-79.798-79.8-33.598-19.607-70.277-29.408-110.063-29.408-39.781 0-76.472 9.804-110.063 29.408-33.596 19.605-60.192 46.204-79.8 79.8C9.803 148.168 0 184.854 0 224.63c0 47.78 13.94 90.745 41.827 128.906 27.884 38.164 63.906 64.572 108.063 79.227 5.14.954 8.945.283 11.419-1.996 2.475-2.282 3.711-5.14 3.711-8.562 0-.571-.049-5.708-.144-15.417a2549.81 2549.81 0 0 1-.144-25.406l-6.567 1.136c-4.187.767-9.469 1.092-15.846 1-6.374-.089-12.991-.757-19.842-1.999-6.854-1.231-13.229-4.086-19.13-8.559-5.898-4.473-10.085-10.328-12.56-17.556l-2.855-6.57c-1.903-4.374-4.899-9.233-8.992-14.559-4.093-5.331-8.232-8.945-12.419-10.848l-1.999-1.431c-1.332-.951-2.568-2.098-3.711-3.429-1.142-1.331-1.997-2.663-2.568-3.997-.572-1.335-.098-2.43 1.427-3.289 1.525-.859 4.281-1.276 8.28-1.276l5.708.853c3.807.763 8.516 3.042 14.133 6.851 5.614 3.806 10.229 8.754 13.846 14.842 4.38 7.806 9.657 13.754 15.846 17.847 6.184 4.093 12.419 6.136 18.699 6.136 6.28 0 11.704-.476 16.274-1.423 4.565-.952 8.848-2.383 12.847-4.285 1.713-12.758 6.377-22.559 13.988-29.41-10.848-1.14-20.601-2.857-29.264-5.14-8.658-2.286-17.605-5.996-26.835-11.14-9.235-5.137-16.896-11.516-22.985-19.126-6.09-7.614-11.088-17.61-14.987-29.979-3.901-12.374-5.852-26.648-5.852-42.826 0-23.035 7.52-42.637 22.557-58.817-7.044-17.318-6.379-36.732 1.997-58.24 5.52-1.715 13.706-.428 24.554 3.853 10.85 4.283 18.794 7.952 23.84 10.994 5.046 3.041 9.089 5.618 12.135 7.708 17.705-4.947 35.976-7.421 54.818-7.421s37.117 2.474 54.823 7.421l10.849-6.849c7.419-4.57 16.18-8.758 26.262-12.565 10.088-3.805 17.802-4.853 23.134-3.138 8.562 21.509 9.325 40.922 2.279 58.24 15.036 16.18 22.559 35.787 22.559 58.817 0 16.178-1.958 30.497-5.853 42.966-3.9 12.471-8.941 22.457-15.125 29.979-6.191 7.521-13.901 13.85-23.131 18.986-9.232 5.14-18.182 8.85-26.84 11.136-8.662 2.286-18.415 4.004-29.263 5.146 9.894 8.562 14.842 22.077 14.842 40.539v60.237c0 3.422 1.19 6.279 3.572 8.562 2.379 2.279 6.136 2.95 11.276 1.995 44.163-14.653 80.185-41.062 108.068-79.226 27.88-38.161 41.825-81.126 41.825-128.906-.01-39.771-9.818-76.454-29.414-110.049z"></path></g></svg>
<span>Edit on GitHub</span>
</a>
<style>
a {
display: flex;
align-items: center;
gap: 0.5rem;
}
</style>

13
examples/doc/src/components/EditOnGithub.tsx Normal file
View file

@ -0,0 +1,13 @@
import type { FunctionalComponent } from 'preact';
import { h } from 'preact';
const EditOnGithub: FunctionalComponent<{ href: string }> = ({ href }) => {
return (
<a class="edit-on-github" href={href}>
<svg preserveAspectRatio="xMidYMid meet" height="1em" width="1em" fill="currentColor" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 438.549 438.549" stroke="none" class="icon-7f6730be--text-3f89f380"><g><path d="M409.132 114.573c-19.608-33.596-46.205-60.194-79.798-79.8-33.598-19.607-70.277-29.408-110.063-29.408-39.781 0-76.472 9.804-110.063 29.408-33.596 19.605-60.192 46.204-79.8 79.8C9.803 148.168 0 184.854 0 224.63c0 47.78 13.94 90.745 41.827 128.906 27.884 38.164 63.906 64.572 108.063 79.227 5.14.954 8.945.283 11.419-1.996 2.475-2.282 3.711-5.14 3.711-8.562 0-.571-.049-5.708-.144-15.417a2549.81 2549.81 0 0 1-.144-25.406l-6.567 1.136c-4.187.767-9.469 1.092-15.846 1-6.374-.089-12.991-.757-19.842-1.999-6.854-1.231-13.229-4.086-19.13-8.559-5.898-4.473-10.085-10.328-12.56-17.556l-2.855-6.57c-1.903-4.374-4.899-9.233-8.992-14.559-4.093-5.331-8.232-8.945-12.419-10.848l-1.999-1.431c-1.332-.951-2.568-2.098-3.711-3.429-1.142-1.331-1.997-2.663-2.568-3.997-.572-1.335-.098-2.43 1.427-3.289 1.525-.859 4.281-1.276 8.28-1.276l5.708.853c3.807.763 8.516 3.042 14.133 6.851 5.614 3.806 10.229 8.754 13.846 14.842 4.38 7.806 9.657 13.754 15.846 17.847 6.184 4.093 12.419 6.136 18.699 6.136 6.28 0 11.704-.476 16.274-1.423 4.565-.952 8.848-2.383 12.847-4.285 1.713-12.758 6.377-22.559 13.988-29.41-10.848-1.14-20.601-2.857-29.264-5.14-8.658-2.286-17.605-5.996-26.835-11.14-9.235-5.137-16.896-11.516-22.985-19.126-6.09-7.614-11.088-17.61-14.987-29.979-3.901-12.374-5.852-26.648-5.852-42.826 0-23.035 7.52-42.637 22.557-58.817-7.044-17.318-6.379-36.732 1.997-58.24 5.52-1.715 13.706-.428 24.554 3.853 10.85 4.283 18.794 7.952 23.84 10.994 5.046 3.041 9.089 5.618 12.135 7.708 17.705-4.947 35.976-7.421 54.818-7.421s37.117 2.474 54.823 7.421l10.849-6.849c7.419-4.57 16.18-8.758 26.262-12.565 10.088-3.805 17.802-4.853 23.134-3.138 8.562 21.509 9.325 40.922 2.279 58.24 15.036 16.18 22.559 35.787 22.559 58.817 0 16.178-1.958 30.497-5.853 42.966-3.9 12.471-8.941 22.457-15.125 29.979-6.191 7.521-13.901 13.85-23.131 18.986-9.232 5.14-18.182 8.85-26.84 11.136-8.662 2.286-18.415 4.004-29.263 5.146 9.894 8.562 14.842 22.077 14.842 40.539v60.237c0 3.422 1.19 6.279 3.572 8.562 2.379 2.279 6.136 2.95 11.276 1.995 44.163-14.653 80.185-41.062 108.068-79.226 27.88-38.161 41.825-81.126 41.825-128.906-.01-39.771-9.818-76.454-29.414-110.049z"></path></g></svg>
<span>Edit on GitHub</span>
</a>
);
}
export default EditOnGithub;

21
examples/doc/src/components/SiteSidebar.astro
View file

@ -3,19 +3,18 @@ import { sidebar } from '../config.ts';
---
<nav>
<ul>
{sidebar.map(category => ([
<ul class="nav-groups">
{sidebar.map(category => (
<li>
<h3>{category.text}</h3>
</li>,
<li>
<ul>
{category.children.map(child => (
<li><a href={child.link}>{child.text}</a></li>
))}
</ul>
<div class="nav-group">
<h4 class="nav-group-title">{category.text}</h4>
<ul>
{category.children.map(child => (
<li class="nav-link"><a href={child.link}>{child.text}</a></li>
))}
</ul>
</div>
</li>
]
))}
</ul>
</nav>

22
examples/doc/src/config.ts
View file

@ -2,26 +2,8 @@ export const sidebar = [
{
text: 'Introduction',
children: [
{ text: 'What is Astro?', link: '/' },
{ text: 'Getting Started', link: '/guide/getting-started' },
{ text: 'Configuration', link: '/guide/configuration' },
{ text: 'Asset Handling', link: '/guide/assets' },
{ text: 'Markdown Extensions', link: '/guide/markdown' },
{ text: 'Using Vue in Markdown', link: '/guide/using-vue' },
{ text: 'Deploying', link: '/guide/deploy' }
]
},
{
text: 'Advanced',
children: [
{ text: 'Frontmatter', link: '/guide/frontmatter' },
{ text: 'Global Computed', link: '/guide/global-computed' },
{ text: 'Global Component', link: '/guide/global-component' },
{ text: 'Customization', link: '/guide/customization' },
{
text: 'Differences from Vuepress',
link: '/guide/differences-from-vuepress'
}
{ text: 'Welcome', link: '/' },
{ text: 'Example', link: '/example' }
]
}
]

10
examples/doc/src/layouts/Main.astro
View file

@ -1,10 +1,14 @@
---
import ArticleFooter from '../components/ArticleFooter.astro';
import SiteSidebar from '../components/SiteSidebar.astro';
import DocSidebar from '../components/DocSidebar.astro';
import ThemeToggle from '../components/ThemeToggle.tsx';
import DocSidebar from '../components/DocSidebar.tsx';
export let content;
const headers = content?.astro?.headers;
let editHref = Astro?.request?.url?.pathname?.slice(1) ?? '';
if (editHref === '') editHref = `index`;
editHref = `https://github.com/snowpackjs/astro/tree/main/examples/doc/src/pages/${editHref}.md`
---
<html>
@ -147,7 +151,7 @@ export let content;
@media (min-width: 88em) {
.layout {
grid-template-columns: minmax(var(--gutter), 1fr) 20rem minmax(0, var(--max-width)) 12rem minmax(var(--gutter), 1fr);
grid-template-columns: minmax(var(--gutter), 1fr) 20rem minmax(0, var(--max-width)) 16rem minmax(var(--gutter), 1fr);
padding-left: 0;
padding-right: 0;
}
@ -210,7 +214,7 @@ export let content;
</article>
</div>
<aside class="sidebar" id="sidebar-content">
<DocSidebar />
<DocSidebar:idle headers={headers} editHref={editHref} />
</aside>
</main>
</body>

35
examples/doc/src/pages/example.md Normal file
View file

@ -0,0 +1,35 @@
---
layout: ../layouts/Main.astro
---
# Markdown example
This is a fully-featured page, written in Markdown!
## Section A
Lorem ipsum dolor sit amet, **consectetur adipiscing elit**. Sed ut tortor _suscipit_, posuere ante id, vulputate urna. Pellentesque molestie aliquam dui sagittis aliquet. Sed sed felis convallis, lacinia lorem sit amet, fermentum ex. Etiam hendrerit mauris at elementum egestas. Vivamus id gravida ante. Praesent consectetur fermentum turpis, quis blandit tortor feugiat in. Aliquam erat volutpat. In elementum purus et tristique ornare. Suspendisse sollicitudin dignissim est a ultrices. Pellentesque sed ipsum finibus, condimentum metus eget, sagittis elit. Sed id lorem justo. Vivamus in sem ac mi molestie ornare.
## Section B
Nam quam dolor, pellentesque sed odio euismod, feugiat tempus tellus. Quisque arcu velit, ultricies in faucibus sed, ultrices ac enim. Nunc eget dictum est. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam ex nisi, egestas mollis ultricies ut, laoreet suscipit libero. Nam condimentum molestie turpis. Sed vestibulum sagittis congue. Maecenas tristique enim et tincidunt tempor. Curabitur ac scelerisque nulla, in malesuada libero. Praesent eu tempus odio. Pellentesque aliquam ullamcorper quam at gravida. Sed non fringilla mauris. Aenean sit amet ultrices erat. Vestibulum congue venenatis tortor, nec suscipit tortor. Aenean pellentesque mauris eget tortor tincidunt pharetra.
## Section C
```markdown
---
layout: ../layouts/Main.astro
---
# Markdown example
This is a fully-featured page, written in Markdown!
## Section A
Lorem ipsum dolor sit amet, **consectetur adipiscing elit**. Sed ut tortor _suscipit_, posuere ante id, vulputate urna. Pellentesque molestie aliquam dui sagittis aliquet. Sed sed felis convallis, lacinia lorem sit amet, fermentum ex. Etiam hendrerit mauris at elementum egestas. Vivamus id gravida ante. Praesent consectetur fermentum turpis, quis blandit tortor feugiat in. Aliquam erat volutpat. In elementum purus et tristique ornare. Suspendisse sollicitudin dignissim est a ultrices. Pellentesque sed ipsum finibus, condimentum metus eget, sagittis elit. Sed id lorem justo. Vivamus in sem ac mi molestie ornare.
## Section B
Nam quam dolor, pellentesque sed odio euismod, feugiat tempus tellus. Quisque arcu velit, ultricies in faucibus sed, ultrices ac enim. Nunc eget dictum est. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam ex nisi, egestas mollis ultricies ut, laoreet suscipit libero. Nam condimentum molestie turpis. Sed vestibulum sagittis congue. Maecenas tristique enim et tincidunt tempor. Curabitur ac scelerisque nulla, in malesuada libero. Praesent eu tempus odio. Pellentesque aliquam ullamcorper quam at gravida. Sed non fringilla mauris. Aenean sit amet ultrices erat. Vestibulum congue venenatis tortor, nec suscipit tortor. Aenean pellentesque mauris eget tortor tincidunt pharetra.
```

129
examples/doc/src/pages/index.astro
View file

@ -1,137 +1,14 @@
---
import Markdown from 'astro/components/Markdown.astro';
import Prism from 'astro/components/Prism.astro';
import Layout from '../layouts/Main.astro';
import Note from '../components/Note.astro';
import CodeBlock from '../components/CodeBlock.tsx';
---
<Layout content={{ title: 'Algolia' }}>
<Layout content={{ title: 'Hello world!' }}>
<Markdown>
# ✍️ Markdown
Astro comes with out-of-the-box Markdown support powered by the expansive [**remark**](https://github.com/remarkjs/remark) ecosystem.
## Remark Plugins
**This is the first draft of Markdown support!** While we plan to support user-provided `remark` plugins soon, our hope is that you won't need `remark` plugins at all!
In addition to [custom components inside the `<Markdown>` component](#markdown-component), Astro comes with [GitHub-flavored Markdown](https://github.github.com/gfm/) support, [Footnotes](https://github.com/remarkjs/remark-footnotes) syntax, [Smartypants](https://github.com/silvenon/remark-smartypants), and syntax highlighting via [Prism](https://prismjs.com/) pre-enabled. These features are likely to be configurable in the future.
### Markdown Pages
Astro treats any `.md` files inside of the `/src/pages` directory as pages. These pages are processed as plain Markdown files and do not support components. If you're looking to embed rich components in your Markdown, take a look at the [Markdown Component](#markdown-component) section.
#### `layout`
The only special Frontmatter key is `layout`, which defines the relative path to a `.astro` component which should wrap your Markdown content.
`src/pages/index.md`
```md
---
layout: ../layouts/main.astro
---
# Hello world!
```
Layout files are normal `.astro` components. Any Frontmatter defined in your `.md` page will be exposed to the Layout component as the `content` prop. `content` also has an `astro` key which holds special metadata about your file, like the complete Markdown `source` and a `headings` object.
This is a starter template, have fun building your next documentation site with [Astro](https://astro.build).
The rendered Markdown content is placed into the default `<slot />` element.
`src/layouts/main.astro`
<!-- <Prism> -->
```jsx
---
export let content;
---
<html>
<head>
<title>{content.title}</title>
</head>
<body>
<slot/>
</body>
</html>
```
<!-- </Prism> -->
### Markdown Component
Similar to tools like [MDX](https://mdxjs.com/) or [MDsveX](https://github.com/pngwn/MDsveX), Astro makes it straightforward to embed rich, interactive components inside of your Markdown content. The `<Markdown>` component is statically rendered, so it does not add any runtime overhead.
Astro exposes a special `Markdown` component for `.astro` files which enables markdown syntax for its children **recursively**. Within the `Markdown` component you may also use plain HTML or any other type of component that is supported by Astro.
````jsx
---
// For now, this import _must_ be named "Markdown" and _must not_ be wrapped with a custom component
// We're working on easing these restrictions!
import Markdown from 'astro/components/Markdown.astro';
import Layout from '../layouts/main.astro';
import MyFancyCodePreview from '../components/MyFancyCodePreview.tsx';
const expressions = 'Lorem ipsum';
---
<Layout>
<Markdown>
# Hello world!
**Everything** supported in a `.md` file is also supported here!
There is _zero_ runtime overhead.
In addition, Astro supports:
- Astro {expressions}
- Automatic indentation normalization
- Automatic escaping of expressions inside code blocks
```jsx
// This content is not transformed!
const object = { someOtherValue };
```
- Rich component support like any `.astro` file!
- Recursive Markdown support (Component children are also processed as Markdown)
<MyFancyCodePreview:visible>
```jsx
const object = { someOtherValue };
```
</MyFancyCodePreview:visible>
</Markdown>
</Layout>
````
### Remote Markdown
If you have Markdown in a remote source, you may pass it directly to the Markdown component. For example, the example below fetches the README from Snowpack's GitHub repository and renders it as HTML.
```jsx
---
import Markdown from 'astro/components/Markdown.astro';
const content = await fetch('https://raw.githubusercontent.com/snowpackjs/snowpack/main/README.md').then(res => res.text());
---
<Layout>
<Markdown>{content}</Markdown>
</Layout>
```
### Security FAQs
**Aren't there security concerns to rendering remote markdown directly to HTML?**
Yes! Just like with regular HTML, improper use the `<Markdown>` component can open you up to a [cross-site scripting (XSS)](https://en.wikipedia.org/wiki/Cross-site_scripting) attack. If you are rendering untrusted content, be sure to _santize your content **before** rendering it_.
**Why not use a prop like React's `dangerouslySetInnerHTML={{ __html: content }}`?**
Rendering a string of HTML (or Markdown) is an extremely common use case when rendering a static site and you probably don't need the extra hoops to jump through. Rendering untrusted content is always dangerous! Be sure to _santize your content **before** rendering it_.
It offers the right mix of simple-to-use [Markdown pages](/example) and rich, interactive components embedded in `.astro` files using `<Markdown>`.
</Markdown>
</Layout>

15
packages/astro/components/Prism.astro
View file

@ -10,12 +10,12 @@ const languageMap = new Map([
['ts', 'typescript']
]);
if(lang == null) {
if (lang == null) {
console.warn('Prism.astro: No language provided.');
}
const ensureLoaded = lang => {
if(!Prism.languages[lang]) {
if(lang && !Prism.languages[lang]) {
loadLanguages([lang]);
}
};
@ -30,14 +30,17 @@ if(languageMap.has(lang)) {
ensureLoaded(lang);
}
if(!Prism.languages[lang]) {
if(lang && !Prism.languages[lang]) {
console.warn(`Unable to load the language: ${lang}`);
}
const grammar = Prism.languages[lang];
let html = Prism.highlight(code, grammar, lang);
let html = code;
if (grammar) {
html = Prism.highlight(code, grammar, lang);
}
let className = `language-${lang}`;
let className = lang ? `language-${lang}` : '';
---
<pre class={className}><code class={className}>{html}</code></pre>
<pre class={className}><code class={className} />{html}</pre>