Skip to content
This repository was archived by the owner on Nov 24, 2023. It is now read-only.

Commit b3c97f4

Browse files
astrobot-houstonaumetra
authored andcommitted
Initial commit from Astro
0 parents  commit b3c97f4

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+5912
-0
lines changed

.gitignore

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# build output
2+
dist/
3+
# generated types
4+
.astro/
5+
6+
# dependencies
7+
node_modules/
8+
9+
# logs
10+
npm-debug.log*
11+
yarn-debug.log*
12+
yarn-error.log*
13+
pnpm-debug.log*
14+
15+
16+
# environment variables
17+
.env
18+
.env.production
19+
20+
# macOS-specific files
21+
.DS_Store

.vscode/extensions.json

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"recommendations": ["astro-build.astro-vscode"],
3+
"unwantedRecommendations": []
4+
}

.vscode/launch.json

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"version": "0.2.0",
3+
"configurations": [
4+
{
5+
"command": "./node_modules/.bin/astro dev",
6+
"name": "Development server",
7+
"request": "launch",
8+
"type": "node-terminal"
9+
}
10+
]
11+
}

README.md

+179
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# Astro Starter Kit: Docs Site
2+
3+
```bash
4+
npm create astro@latest -- --template docs
5+
```
6+
7+
[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/astro/tree/latest/examples/docs)
8+
[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/astro/tree/latest/examples/docs)
9+
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/withastro/astro?devcontainer_path=.devcontainer/docs/devcontainer.json)
10+
11+
> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
12+
13+
![docs](https://user-images.githubusercontent.com/4677417/186189283-0831b9ab-d6b9-485d-8955-3057e532ab31.png)
14+
15+
## Features
16+
17+
-**Full Markdown support**
18+
-**Responsive mobile-friendly design**
19+
-**Sidebar navigation**
20+
-**Search (powered by Algolia)**
21+
-**Multi-language i18n**
22+
-**Automatic table of contents**
23+
-**Automatic list of contributors**
24+
- ✅ (and, best of all) **dark mode**
25+
26+
## 🧞 Commands
27+
28+
All commands are run from the root of the project, from a terminal:
29+
30+
| Command | Action |
31+
| :--------------------- | :----------------------------------------------- |
32+
| `npm install` | Installs dependencies |
33+
| `npm run dev` | Starts local dev server at `localhost:3000` |
34+
| `npm run build` | Build your production site to `./dist/` |
35+
| `npm run preview` | Preview your build locally, before deploying |
36+
| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` |
37+
| `npm run astro --help` | Get help using the Astro CLI |
38+
39+
To deploy your site to production, check out our [Deploy an Astro Website](https://docs.astro.build/guides/deploy) guide.
40+
41+
## 👀 Want to learn more?
42+
43+
Feel free to check [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat).
44+
45+
## Customize This Theme
46+
47+
### Site metadata
48+
49+
`src/consts.ts` contains several data objects that describe metadata about your site like title, description, default language, and Open Graph details. You can customize these to match your project.
50+
51+
### CSS styling
52+
53+
The theme's look and feel is controlled by a few key variables that you can customize yourself. You'll find them in the `src/styles/theme.css` CSS file.
54+
55+
If you've never worked with CSS variables before, give [MDN's guide on CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) a quick read.
56+
57+
This theme uses a "cool blue" accent color by default. To customize this for your project, change the `--theme-accent` variable to whatever color you'd like:
58+
59+
```diff
60+
/* src/styles/theme.css */
61+
:root {
62+
color-scheme: light;
63+
- --theme-accent: hsla(var(--color-blue), 1);
64+
+ --theme-accent: hsla(var(--color-red), 1); /* or: hsla(#FF0000, 1); */
65+
```
66+
67+
## Page metadata
68+
69+
Astro uses frontmatter in Markdown pages to choose layouts and pass properties to those layouts. If you are using the default layout, you can customize the page in many different ways to optimize SEO and other things. For example, you can use the `title` and `description` properties to set the document title, meta title, meta description, and Open Graph description.
70+
71+
```markdown
72+
---
73+
title: Example title
74+
description: Really cool docs example that uses Astro
75+
layout: ../../layouts/MainLayout.astro
76+
---
77+
78+
# Page content...
79+
```
80+
81+
For more SEO related properties, look at `src/components/HeadSEO.astro`
82+
83+
### Sidebar navigation
84+
85+
The sidebar navigation is controlled by the `SIDEBAR` variable in your `src/consts.ts` file. You can customize the sidebar by modifying this object. A default, starter navigation has already been created for you.
86+
87+
```ts
88+
export const SIDEBAR = {
89+
en: {
90+
'Section Header': [
91+
{ text: 'Introduction', link: 'en/introduction' },
92+
{ text: 'Page 2', link: 'en/page-2' },
93+
{ text: 'Page 3', link: 'en/page-3' },
94+
],
95+
'Another Section': [{ text: 'Page 4', link: 'en/page-4' }],
96+
},
97+
};
98+
```
99+
100+
Note the top-level `en` key: This is needed for multi-language support. You can change it to whatever language you'd like, or add new languages as you go. More details on this below.
101+
102+
### Multiple Languages support
103+
104+
The Astro docs template supports multiple languages out of the box. The default theme only shows `en` documentation, but you can enable multi-language support features by adding a second language to your project.
105+
106+
To add a new language to your project, you'll want to extend the current `src/content/docs/[lang]/...` layout:
107+
108+
```diff
109+
📂 src/content/docs
110+
┣ 📂 en
111+
┃ ┣ 📜 page-1.md
112+
┃ ┣ 📜 page-2.md
113+
┃ ┣ 📜 page-3.astro
114+
+ ┣ 📂 es
115+
+ ┃ ┣ 📜 page-1.md
116+
+ ┃ ┣ 📜 page-2.md
117+
+ ┃ ┣ 📜 page-3.astro
118+
```
119+
120+
You'll also need to add the new language name to the `KNOWN_LANGUAGES` map in your `src/consts.ts` file. This will enable your new language switcher in the site header.
121+
122+
```diff
123+
// src/consts.ts
124+
export const KNOWN_LANGUAGES = {
125+
English: 'en',
126+
+ Spanish: 'es',
127+
};
128+
```
129+
130+
Last step: you'll need to add a new entry to your sidebar, to create the table of contents for that language. While duplicating every page might not sound ideal to everyone, this extra control allows you to create entirely custom content for every language.
131+
132+
> Make sure the sidebar `link` value points to the correct language!
133+
134+
```diff
135+
// src/consts.ts
136+
export const SIDEBAR = {
137+
en: {
138+
'Section Header': [
139+
{ text: 'Introduction', link: 'en/introduction' },
140+
// ...
141+
],
142+
// ...
143+
},,
144+
+ es: {
145+
+ 'Encabezado de sección': [
146+
+ { text: 'Introducción', link: 'en/introduction' },
147+
+ // ...
148+
+ ],
149+
+ // ...
150+
+ },
151+
};
152+
153+
// ...
154+
```
155+
156+
If you plan to use Spanish as the default language, you just need to modify the redirect path in `src/pages/index.astro`:
157+
158+
```diff
159+
<script>
160+
- window.location.pathname = `/en/introduction`;
161+
+ window.location.pathname = `/es/introduction`;
162+
</script>
163+
```
164+
165+
You can also remove the above script and write a landing page in Spanish instead.
166+
167+
### What if I don't plan to support multiple languages?
168+
169+
That's totally fine! Not all projects need (or can support) multiple languages. You can continue to use this theme without ever adding a second language.
170+
171+
If that single language is not English, you can just replace `en` in directory layouts and configurations with the preferred language.
172+
173+
### Search (Powered by Algolia)
174+
175+
[Algolia](https://www.algolia.com/) offers a free service to qualified open source projects called [DocSearch](https://docsearch.algolia.com/). If you are accepted to the DocSearch program, provide your API Key & index name in `src/consts.ts` and a search box will automatically appear in your site header.
176+
177+
Note that Algolia and Astro are not affiliated. We have no say over acceptance to the DocSearch program.
178+
179+
If you'd prefer to remove Algolia's search and replace it with your own, check out the `src/components/Header.astro` component to see where the component is added.

astro.config.mjs

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
import { defineConfig } from 'astro/config';
2+
import preact from '@astrojs/preact';
3+
import react from '@astrojs/react';
4+
5+
// https://astro.build/config
6+
export default defineConfig({
7+
integrations: [
8+
// Enable Preact to support Preact JSX components.
9+
preact(),
10+
// Enable React for the Algolia search component.
11+
react(),
12+
],
13+
site: `https://astro.build`,
14+
});

package.json

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
{
2+
"name": "kitsune-docs",
3+
"type": "module",
4+
"version": "0.0.1",
5+
"scripts": {
6+
"dev": "astro dev",
7+
"start": "astro dev",
8+
"build": "astro build",
9+
"preview": "astro preview",
10+
"astro": "astro"
11+
},
12+
"dependencies": {
13+
"astro": "^2.1.7",
14+
"preact": "^10.7.3",
15+
"react": "^18.1.0",
16+
"react-dom": "^18.1.0",
17+
"@astrojs/react": "^2.1.0",
18+
"@astrojs/preact": "^2.1.0",
19+
"@algolia/client-search": "^4.13.1",
20+
"@docsearch/css": "^3.1.0",
21+
"@docsearch/react": "^3.1.0",
22+
"@types/react": "^17.0.45",
23+
"@types/node": "^18.0.0",
24+
"@types/react-dom": "^18.0.0"
25+
},
26+
"devDependencies": {
27+
"html-escaper": "^3.0.3"
28+
}
29+
}

public/default-og-image.png

731 KB
Loading

public/favicon.svg

+9
Loading
+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Array.from(document.getElementsByTagName('pre')).forEach((element) => {
2+
element.setAttribute('tabindex', '0');
3+
});

0 commit comments

Comments
 (0)