Skip to content

Commit c354797

Browse files
SuperCHIROK1SuperCHIROK1
authored
Initial commit
0 parents  commit c354797

27 files changed

Lines changed: 8279 additions & 0 deletions

‎.devcontainer/devcontainer.json‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
{
2+
"name": "30DaysOf Astro Template",
3+
"image": "mcr.microsoft.com/devcontainers/universal:2",
4+
5+
"waitFor": "onCreateCommand",
6+
"updateContentCommand": "",
7+
"postCreateCommand": "",
8+
"customizations": {
9+
"codespaces": {
10+
"openFiles": []
11+
},
12+
"vscode": {
13+
"extensions": [
14+
"astro-build.astro-vscode",
15+
]
16+
}
17+
}
18+
}

‎.github/workflows/deploy.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
# Trigger the workflow every time you push to the `main` branch
5+
# Using a different branch name? Replace `main` with your branch’s name
6+
push:
7+
branches: [ main ]
8+
# Allows you to run this workflow manually from the Actions tab on GitHub.
9+
workflow_dispatch:
10+
11+
# Allow this job to clone the repo and create a page deployment
12+
permissions:
13+
contents: read
14+
pages: write
15+
id-token: write
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout your repository using git
22+
uses: actions/checkout@v3
23+
- name: Install, build, and upload your site
24+
uses: withastro/action@v0
25+
with:
26+
path: ./website # The root location of your Astro project inside the repository. (optional)
27+
# node-version: 16 # The specific version of Node that should be used to build your site. Defaults to 16. (optional)
28+
# package-manager: yarn # The Node package manager that should be used to install dependencies and build your site. Automatically detected based on your lockfile. (optional)
29+
30+
deploy:
31+
needs: build
32+
runs-on: ubuntu-latest
33+
environment:
34+
name: github-pages
35+
url: ${{ steps.deployment.outputs.page_url }}
36+
steps:
37+
- name: Deploy to GitHub Pages
38+
id: deployment
39+
uses: actions/deploy-pages@v1

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2023 #30DaysOf
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# Astro Starlight On GitHub Pages
2+
3+
> Objectives
4+
5+
Build and deploy an Astro Starlight Documentation site to GitHub Pages.
6+
Explore features and customization - validate its use as reusable template.
7+
8+
---
9+
10+
## 1. Why Astro?
11+
12+
Astro is a free, open-source option for static site generation that bills itself as _the all-in-one web framework designed for speed_. Three features that make it interesting:
13+
- Islands architecture - with **zero client-side JS**
14+
- Plays well with others - **bring your own components**
15+
- Rich ecosystem - **content focused & community-driven**
16+
17+
This gives you the benefits of performance & flexibility, with rich themes and integrations for quickstart adoption. It's a rising star for JS frameworks and used by industry teams - stability ftw.
18+
19+
---
20+
21+
## 2. Why Starlight?
22+
23+
Astro has a [large collection of themes](https://astro.build/themes) supporting different site categories and frontend technology components. The ["Official" filter](https://astro.build/themes?search=&categories%5B%5D=official) identifies themes created by the Astro team. [Starlight](https://astro.build/themes/details/starlight/) is the default **documentation focused** framework from Astro, currently in very early release. It promises:
24+
- fast, accessible, easy-to-use websites
25+
- site-navigation, search, i18n, SEO support
26+
- code highlighting, dark mode, easy-to-read typography
27+
- write in Markdown, MDX or Markdoc
28+
29+
Plus all Astro benefits (e.g., bring your own UI components).
30+
31+
- [See the GitHub Repo](https://github.com/withastro/starlight)
32+
- [Read the Docs](https://starlight.astro.build/)
33+
- [Get Started](https://starlight.astro.build/getting-started/)
34+
35+
---
36+
37+
## 3. Quickstart
38+
39+
1. Verify you have Node.js installed. I use `nvm` and default to the LTS version for Node.js.
40+
41+
```bash
42+
$ nvm use --lts
43+
Now using node v18.16.0 (npm v9.6.7)
44+
```
45+
46+
2. Scaffold out a Starlight project with Astro.
47+
48+
```bash
49+
$ npm create astro@latest -- --template starlight
50+
```
51+
52+
As part of setup, you define the destination folder (`website`), install dependencies and configure Typescript, git usage if needed. You can also disable telemetry capture using `npx astro telemetry disable` at this time.
53+
54+
3. Preview the default Starlight site.
55+
56+
```bash
57+
$ cd website
58+
$ npm run dev
59+
```
60+
61+
This runs a dev server on `http://localhost:3001` which watches `src/content` for changes (hot reload).
62+
63+
4. Open the browser to that URL and let's see what we got:
64+
65+
> A Landing Page (Light Mode)
66+
67+
![Starlight Landing Page, Light mode](./static/02-landing-light.png)
68+
69+
> A Landing Page (Dark Mode)
70+
71+
![Starlight Landing Page, Dark mode](./static/01-landing-dark.png)
72+
73+
> A Documentation Page (Default)
74+
75+
![Starlight Documentation Page, Default](./static/03-page-original.png)
76+
77+
> The Documentation Page Updated (Hot Reload)
78+
79+
![Starlight Documentation Page, Updated](./static/04-page-updated.png)
80+
81+
> The Search Feature (oh-oh!)
82+
83+
![Starlight Search Feature, Disabled](./static/05-default-search.png)
84+
85+
5. Alright, let's try to build the **production** version of the site locally.
86+
87+
```bash
88+
$ cd website
89+
$ npm run build
90+
...
91+
...
92+
Finished in 0.13 seconds
93+
08:53:44 PM [build] 4 page(s) built in 4.61s
94+
08:53:44 PM [build] Complete!
95+
```
96+
6. You'll notice this builds the production version in the `dist` folder. Let's preview it.
97+
98+
```bash
99+
$ npm run preview
100+
```
101+
The output indicates the production server is running at `http://localhost:3000` - let's open that up. You see the same pages as before - but now let's try search. _In fact, let's search for the changed text from above to see if it can be found_.
102+
103+
> Search for "Related References" in Production
104+
105+
OMG - it works!! We didn't have to do anything extra to activate search indexes. Basic keyword search out of the box!
106+
107+
![Starlight Production Preview, search](./static/06-production-search.png)
108+
109+
---
110+
111+
## 4. Deployment
112+
113+
Before we explore deploying the production build to GitHub Pages, let's commit the current version. **Done!**
114+
115+
Now, let's [deploy the Astro Site to GitHub Pages](https://docs.astro.build/en/guides/deploy/github/). Astro provides an official `withastro/action` that should make this easy.
116+
117+
1. Set `site` and `base` options in `astro.config.js`
118+
2. Create `.github/workflows/deploy.yml` and copy [the provided workflow](https://docs.astro.build/en/guides/deploy/github/).
119+
3. Since we have our site source in the `website/` subfolder (vs. root of repo), uncomment the `with` section of the install steps in workflow and set the `path` to `./website`
120+
4. Go to the GitHub repo's [Settings > Pages](https://github.com/30DaysOf/astro-starlight-ghpages/settings/pages) configuration. Choose `GitHub Actions` as the Source of your site.
121+
122+
**Commit the changes in your code to GitHub**. You should see the deploy action run. If successful, the GitHub Pages endpoint should show the deployed site. It's LIVE! [https://30daysof.github.io/astro-starlight-ghpages/](https://30daysof.github.io/astro-starlight-ghpages/)!!
123+
124+
125+
> Issue: Hero links not resolving base path correctly
126+
127+
The "Example Guide" button on the landing page is mapped to "/guides/example/" but when clicked, does not take base prefix (repo path) into account, resulting in a 404. The same route used from the sidebar works just fine. **I am assuming this has to do with the difference in how links are resolved in frontmatter vs. markdown** _Issue raised in community chat. Waiting for response_.
128+
129+
---
130+
131+
## 7. Adding Blog
132+
133+
The [Starlight Blog](https://starlight-blog-docs.vercel.app/getting-started/) plugin from the community adds the blog feature to the default Starlight theme. Let's try it out.
134+
135+
1. Install the plugin.
136+
137+
```bash
138+
$ npm install starlight-blog --save
139+
```
140+
2. Add the plugin to `astro.config.mjs` and configure it.
141+
142+
```javascript
143+
import starlight from '@astrojs/starlight'
144+
import { defineConfig } from 'astro/config'
145+
import starlightBlog from 'starlight-blog'
146+
147+
export default defineConfig({
148+
integrations: [
149+
starlight({
150+
plugins: [starlightBlog()],
151+
title: 'My Docs',
152+
}),
153+
],
154+
})
155+
```
156+
3. Customize [configuration](https://starlight-blog-docs.vercel.app/configuration) if needed.
157+
158+
```javascript
159+
import starlight from '@astrojs/starlight'
160+
import { defineConfig } from 'astro/config'
161+
import starlightBlog from 'starlight-blog'
162+
163+
export default defineConfig({
164+
integrations: [
165+
starlight({
166+
plugins: [
167+
starlightBlog({
168+
title: "Blog",
169+
postCount: 7,
170+
recentPostCount: 1,
171+
authors: {
172+
nitya: {
173+
name: "Nitya",
174+
picture: "https://github.com/nitya.png",
175+
url: "https://github.com/nitya",
176+
title: "AI, Art & Advocacy @Microsoft",
177+
}
178+
},
179+
}),
180+
],
181+
title: 'My Docs',
182+
}),
183+
],
184+
})
185+
```
186+
4. Extend the frontmatter schema
187+
188+
```javascript
189+
import { defineCollection } from 'astro:content';
190+
import { docsSchema, i18nSchema } from '@astrojs/starlight/schema';
191+
import { blogSchema } from 'starlight-blog/schema'
192+
193+
export const collections = {
194+
docs: defineCollection({ schema: docsSchema({ extend: blogSchema() }) }),
195+
i18n: defineCollection({ type: 'data', schema: i18nSchema() }),
196+
};
197+
```
198+
199+
5. Now write your first blog post under `src/content/docs/blog` and see it show up in sidebar of blog. Update the link paths if needed.

‎static/01-landing-dark.png‎

179 KB
Loading

‎static/02-landing-light.png‎

179 KB
Loading

‎static/03-page-original.png‎

65.9 KB
Loading

‎static/04-page-updated.png‎

65.1 KB
Loading

‎static/05-default-search.png‎

65.9 KB
Loading

‎static/06-production-search.png‎

293 KB
Loading

0 commit comments

Comments
 (0)