feat!: relaunch w/ Astro.js starlight backed documentation

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

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

.devcontainer/devcontainer.json

@@ -8,11 +8,7 @@
   "postStartCommand": "make serve",
   "customizations": {
     "vscode": {
-      "extensions": [
-        "sissel.shopify-liquid",
-        "esbenp.prettier-vscode",
-        "ms-vscode.makefile-tools"
-      ]
+      "extensions": ["esbenp.prettier-vscode", "ms-vscode.makefile-tools"]
     }
   }
 }

.github/copilot-instructions.md

@@ -0,0 +1,88 @@
+# html2rss.github.io – Copilot Instructions
+
+# Role and Objective
+
+You are an Expert in modern web development, Astro, and Starlight documentation.
+You are focused on creating accessible, fast, and maintainable documentation websites.
+You are documenting the [html2rss project](https://github.com/html2rss/) and its components.
+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.
+
+## Purpose
+
+Build and maintain the html2rss documentation website using Astro and Starlight.
+Create comprehensive, user-friendly documentation that showcases html2rss capabilities.
+
+## Core Stack
+
+- **Astro** – static site generator
+- **Starlight** – documentation framework for Astro
+- **TypeScript** – type safety
+- **MDX** – enhanced markdown with components
+
+## Architecture
+
+- **Content** – MDX files in `src/content/docs/`
+- **Components** – reusable UI components in `src/components/`
+- **Pages** – custom pages in `src/pages/`
+- **Styling** – CSS modules or Tailwind
+- **Assets** – images, icons in `public/`
+
+## Coding Rules
+
+- Target modern browsers (ES2020+)
+- Use TypeScript for all `.ts` files
+- Prefer functional components
+- Use semantic HTML
+- Follow accessibility guidelines (WCAG 2.1)
+- Optimize for Core Web Vitals
+- Use Astro's built-in optimizations
+
+## Content Rules
+
+- Write clear, concise documentation, which a human who is not fully-fluent in "Technology" can understand and work with.
+- Use active voice
+- Include code examples
+- Add interactive demos where helpful
+- Keep navigation logical
+- Use consistent terminology
+- Ensure the Site Navigation is assembled in a logical and user-friendly manner.
+- Prevent adding (and remove existing) "technical clutter" content.
+- follow AIDA-model to craft ensure content is engaging and SEO-friendly
+
+## Performance & SEO
+
+- Optimize images (WebP, proper sizing)
+- Use Astro's built-in lazy loading
+- Implement proper meta tags
+- Ensure fast page loads
+- Use semantic HTML structure
+- Add structured data where appropriate
+
+## Do ✅
+
+- Follow Astro best practices
+- Use Starlight's built-in features
+- Write accessible content
+- Test on multiple devices
+- Optimize for search engines
+- Keep dependencies updated
+
+## Don't ❌
+
+- Don't add unnecessary JavaScript
+- Don't ignore accessibility
+- Don't use outdated patterns
+- Don't skip mobile optimization
+- Don't overcomplicate navigation
+
+## Workflow
+
+1. Read existing content patterns
+2. Code → test locally with `npm run dev`
+3. Build → verify with `npm run build`
+4. Deploy → ensure all pages work
+
+## AI Reference
+
+- [Astro Documentation](https://docs.astro.build/)
+- [Starlight Documentation](https://starlight.astro.build/)

.github/workflows/gh-pages.yml

@@ -18,24 +18,29 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: "npm"
+
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: 3.4
           bundler-cache: true
 
+      - name: Install dependencies
+        run: npm ci
+
       - name: Build the site
-        env:
-          JEKYLL_ENV: production
-        run: |
-          ./bin/data-update
-          bundle exec jekyll build
+        run: npm run build:full
 
       - name: Upload artifact
         uses: actions/upload-artifact@v4
         with:
-          name: _site
-          path: _site
+          name: dist
+          path: dist
 
   deploy:
     runs-on: ubuntu-latest
@@ -49,14 +54,14 @@ jobs:
       - name: Download artifact
         uses: actions/download-artifact@v4
         with:
-          name: _site
-          path: _site
+          name: dist
+          path: dist
 
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./_site
+          publish_dir: ./dist
           publish_branch: master
           force_orphan: true
           user_name: "github-actions[bot]"

.github/workflows/lint.yml

@@ -19,10 +19,10 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: "24"
-          cache: "yarn"
+          cache: "npm"
 
       - name: Install dependencies
-        run: yarn install --frozen-lockfile
+        run: npm ci
 
       - name: Run linters
-        run: yarn lint
+        run: make lint

.gitignore

@@ -1,8 +1,21 @@
-_data/configs.yml
-_site
-.jekyll-cache
-.jekyll-metadata
-.sass-cache
-node_modules
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
 node_modules/
-vendor
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store

.prettierignore

@@ -1,3 +1,3 @@
 _site
 node_modules
-yarn.lock
+package-lock.json

Gemfile

@@ -2,29 +2,5 @@
 
 source 'https://rubygems.org'
 
-gem 'jekyll', '~> 4.4'
-gem 'just-the-docs'
-
 gem 'html2rss', git: 'https://github.com/html2rss/html2rss.git'
 gem 'html2rss-configs', git: 'https://github.com/html2rss/html2rss-configs.git'
-
-group :jekyll_plugins do
-  gem 'jekyll-feed', '~> 0.17'
-  gem 'jekyll-loading-lazy'
-  gem 'jekyll-sitemap'
-  gem 'jekyll-target-blank'
-end
-
-# Windows and JRuby does not include zoneinfo files, so bundle the tzinfo-data gem
-# and associated library.
-platforms :mingw, :x64_mingw, :mswin, :jruby do
-  gem 'tzinfo', '~> 2.0'
-  gem 'tzinfo-data'
-end
-
-# Performance-booster for watching directories on Windows
-gem 'wdm', '~> 0.1.1', platforms: %i[mingw x64_mingw mswin]
-
-group :development do
-  gem 'rubocop', '~> 1.80'
-end