Skip to content

Commit c3a8285

Browse files
gildesmaraisgildesmarais
authored
feat!: relaunch w/ Astro.js starlight backed documentation (#943)
* phase1 * phase 2 * feed directory qa * migrate remaining content * remove the dead jekyll parts * i like to move it, i like to move it move-it … * add missing docs * remove alpine and style * feed-directory kiss * feed directory iterate * feed directory strip out client side js * nav migration to astro starlight * remove duplicated h1s * fix yarn setup, setup prettier w/ astro * remove jekyll backup * h1 fixes * cleanup * style: prettier * review changes * lintfix * fix redirects Signed-off-by: Gil Desmarais <git@desmarais.de> * add ai agent basics * feed directory css clean * docs: codespace note * . * fix navi * . * . * seo * support -> troubleshoot * . * bundle install * ci workflow --------- Signed-off-by: Gil Desmarais <git@desmarais.de>
1 parent 47bb887 commit c3a8285

File tree

121 files changed

+8856
-2979
lines changed

Some content is hidden

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

121 files changed

+8856
-2979
lines changed

‎.cursor/rules/read-copilot-instructions.mdc‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
description: Read and follow .github/copilot-instructions.md for this repo
3+
alwaysApply: true
4+
---
5+
6+
Before assisting, open and read `.github/copilot-instructions.md`.
7+
Follow it as the authoritative source for coding practices, docs style, security, and compliance for this project.
8+
9+
If the file is missing, say so, ask to create it, and proceed with safe defaults.
10+
When “Copilot” is mentioned in that file, interpret it as referring to **you (Cursor)**.
11+
Summarize the relevant sections into your working context before you act.
12+

‎.devcontainer/devcontainer.json‎

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -8,11 +8,7 @@
88
"postStartCommand": "make serve",
99
"customizations": {
1010
"vscode": {
11-
"extensions": [
12-
"sissel.shopify-liquid",
13-
"esbenp.prettier-vscode",
14-
"ms-vscode.makefile-tools"
15-
]
11+
"extensions": ["esbenp.prettier-vscode", "ms-vscode.makefile-tools"]
1612
}
1713
}
1814
}

‎.github/copilot-instructions.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# html2rss.github.io – Copilot Instructions
2+
3+
# Role and Objective
4+
5+
You are an Expert in modern web development, Astro, and Starlight documentation.
6+
You are focused on creating accessible, fast, and maintainable documentation websites.
7+
You are documenting the [html2rss project](https://github.com/html2rss/) and its components.
8+
You are tasked to ensure high-quality, user-friendly documentation that helps users understand and utilize html2rss effectively. This is not limited to just writing content, but also includes structuring, and UX-optimizing the site.
9+
10+
## Purpose
11+
12+
Build and maintain the html2rss documentation website using Astro and Starlight.
13+
Create comprehensive, user-friendly documentation that showcases html2rss capabilities.
14+
15+
## Core Stack
16+
17+
- **Astro** – static site generator
18+
- **Starlight** – documentation framework for Astro
19+
- **TypeScript** – type safety
20+
- **MDX** – enhanced markdown with components
21+
22+
## Architecture
23+
24+
- **Content** – MDX files in `src/content/docs/`
25+
- **Components** – reusable UI components in `src/components/`
26+
- **Pages** – custom pages in `src/pages/`
27+
- **Styling** – CSS modules or Tailwind
28+
- **Assets** – images, icons in `public/`
29+
30+
## Coding Rules
31+
32+
- Target modern browsers (ES2020+)
33+
- Use TypeScript for all `.ts` files
34+
- Prefer functional components
35+
- Use semantic HTML
36+
- Follow accessibility guidelines (WCAG 2.1)
37+
- Optimize for Core Web Vitals
38+
- Use Astro's built-in optimizations
39+
40+
## Content Rules
41+
42+
- Write clear, concise documentation, which a human who is not fully-fluent in "Technology" can understand and work with.
43+
- Use active voice
44+
- Include code examples
45+
- Add interactive demos where helpful
46+
- Keep navigation logical
47+
- Use consistent terminology
48+
- Ensure the Site Navigation is assembled in a logical and user-friendly manner.
49+
- Prevent adding (and remove existing) "technical clutter" content.
50+
- follow AIDA-model to craft ensure content is engaging and SEO-friendly
51+
52+
## Performance & SEO
53+
54+
- Optimize images (WebP, proper sizing)
55+
- Use Astro's built-in lazy loading
56+
- Implement proper meta tags
57+
- Ensure fast page loads
58+
- Use semantic HTML structure
59+
- Add structured data where appropriate
60+
61+
## Do ✅
62+
63+
- Follow Astro best practices
64+
- Use Starlight's built-in features
65+
- Write accessible content
66+
- Test on multiple devices
67+
- Optimize for search engines
68+
- Keep dependencies updated
69+
70+
## Don't ❌
71+
72+
- Don't add unnecessary JavaScript
73+
- Don't ignore accessibility
74+
- Don't use outdated patterns
75+
- Don't skip mobile optimization
76+
- Don't overcomplicate navigation
77+
78+
## Workflow
79+
80+
1. Read existing content patterns
81+
2. Code → test locally with `npm run dev`
82+
3. Build → verify with `npm run build`
83+
4. Deploy → ensure all pages work
84+
85+
## AI Reference
86+
87+
- [Astro Documentation](https://docs.astro.build/)
88+
- [Starlight Documentation](https://starlight.astro.build/)

‎.github/workflows/gh-pages.yml‎

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -18,24 +18,29 @@ jobs:
1818
steps:
1919
- uses: actions/checkout@v4
2020

21+
- name: Set up Node.js
22+
uses: actions/setup-node@v4
23+
with:
24+
node-version: "22"
25+
cache: "npm"
26+
2127
- name: Set up Ruby
2228
uses: ruby/setup-ruby@v1
2329
with:
2430
ruby-version: 3.4
2531
bundler-cache: true
2632

33+
- name: Install dependencies
34+
run: npm ci
35+
2736
- name: Build the site
28-
env:
29-
JEKYLL_ENV: production
30-
run: |
31-
./bin/data-update
32-
bundle exec jekyll build
37+
run: npm run build:full
3338

3439
- name: Upload artifact
3540
uses: actions/upload-artifact@v4
3641
with:
37-
name: _site
38-
path: _site
42+
name: dist
43+
path: dist
3944

4045
deploy:
4146
runs-on: ubuntu-latest
@@ -49,14 +54,14 @@ jobs:
4954
- name: Download artifact
5055
uses: actions/download-artifact@v4
5156
with:
52-
name: _site
53-
path: _site
57+
name: dist
58+
path: dist
5459

5560
- name: Deploy to GitHub Pages
5661
uses: peaceiris/actions-gh-pages@v3
5762
with:
5863
github_token: ${{ secrets.GITHUB_TOKEN }}
59-
publish_dir: ./_site
64+
publish_dir: ./dist
6065
publish_branch: master
6166
force_orphan: true
6267
user_name: "github-actions[bot]"

‎.github/workflows/lint.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,10 +19,10 @@ jobs:
1919
uses: actions/setup-node@v4
2020
with:
2121
node-version: "24"
22-
cache: "yarn"
22+
cache: "npm"
2323

2424
- name: Install dependencies
25-
run: yarn install --frozen-lockfile
25+
run: npm ci
2626

2727
- name: Run linters
28-
run: yarn lint
28+
run: make lint

‎.gitignore‎

Lines changed: 20 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,21 @@
1-
_data/configs.yml
2-
_site
3-
.jekyll-cache
4-
.jekyll-metadata
5-
.sass-cache
6-
node_modules
1+
# build output
2+
dist/
3+
# generated types
4+
.astro/
5+
6+
# dependencies
77
node_modules/
8-
vendor
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

‎.prettierignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
_site
22
node_modules
3-
yarn.lock
3+
package-lock.json

‎.prettierrc.json‎

Lines changed: 0 additions & 4 deletions
This file was deleted.

‎.stylelintrc.json‎

Lines changed: 0 additions & 35 deletions
This file was deleted.

‎404.html‎

Lines changed: 0 additions & 41 deletions
This file was deleted.

0 commit comments

Comments
 (0)