collective-governance-ai/README.md

Collective Governance for AI: Points of Intervention

A single-page, responsive, static website for a digital zine with interactive scroll effects. Built in Astro with Claude Code.

Features

• Markdown-based content: Edit your zine content in src/content/zine.md
• Scroll animations: Sections fade in as you scroll
• ASCII background patterns: Each section has unique repeating ASCII symbols with gradient fades
• Interactive TOC sidebar: Stack-style navigation with connecting lines to current section
• Mobile hamburger menu: Touch-friendly navigation for small screens
• Responsive design: Optimized for all screen sizes
• Zero JavaScript framework: Uses vanilla JavaScript for interactions
• Black-and-white zine aesthetic: Bold typography, rough edges, and texture overlay

Prerequisites

Node.js >= 18.20.8 (or upgrade to Node.js 20+ for best compatibility)

Getting Started

1. Install dependencies:

   npm install
   

2. Start the development server:

   npm run dev
   

3. Build for production:

   npm run build
   

4. Preview production build:

   npm run preview
   

Project Structure

├── src/
│   ├── data/
│   │   └── zine.md          # Your zine content in Markdown
│   └── pages/
│       └── index.astro      # Main page that renders the zine
├── public/                  # Static assets
└── astro.config.mjs         # Astro configuration

Editing Your Zine

1. Open src/data/zine.md
2. Write your content using Markdown
3. Use ## Heading for section breaks (each becomes a full-height section)
4. The dev server will hot-reload your changes

Markdown Tips

• # Main Title - Top-level heading (animated)
• ## Section Title - Creates a new scrolling section
• Regular Markdown formatting works: bold, italic, links, etc.

Customization

Changing ASCII Patterns

Edit the CSS in src/pages/index.astro (lines 198-213) to change the ASCII symbols for each section:

section:nth-child(2)::after { content: '◆ ◇ ◆ ◇ ...' }

Adjusting Colors

All styling is black-and-white by default. Edit the CSS variables:

• Border color: #000000 throughout
• Background: #ffffff
• Hover states: lines 91-95

Adjusting Scroll Effects

Modify the JavaScript in index.astro:

• Intersection threshold: Line 444 (currently 0.15 = 15% visibility)
• Root margin: Line 445 (currently -10% = middle 80% of viewport)
• Scroll behavior: Line 531 ('smooth' for animated scrolling)

Adding More Interactive Elements

The page uses:

• Intersection Observer API for scroll-based section visibility and TOC highlighting
• SVG line drawing for connecting TOC to current section
• CSS animations for fade-in effects
• Mobile menu toggle with hamburger icon

You can extend the JavaScript in the <script> tag for additional interactivity.

Deployment

Configuring the Base Path

If deploying to a subdirectory (e.g., example.com/my-site/), update astro.config.mjs:

export default defineConfig({
  base: '/my-site',  // Change to your subdirectory path
});

For root deployment (example.com/), remove the base option or set it to '/'.

Current configuration: This site is configured for /cg-ai subdirectory.

Building and Deploying

1. Build the site:

   npm run build
   

   This creates a dist/ folder with the optimized static site.

2. Deploy the dist/ folder to your hosting provider:

   • Netlify: Drag and drop dist/ to netlify.com/drop
   • GitHub Pages: Push dist/ contents to gh-pages branch
   • Vercel: Run vercel CLI in project root
   • Any static host: Upload dist/ folder via FTP/SFTP to your web directory

3. Important: Deploy the dist/ folder contents to match your base path:

   • If base: '/cg-ai', upload dist contents to public_html/cg-ai/ on your server
   • If base: '/', upload dist contents to public_html/ (or your web root)

Note: The public/ folder contains source assets, not the production build. Always deploy dist/.

Troubleshooting

Node.js Version Error

If you see "Node.js version not supported", you have two options:

1. Upgrade Node.js (recommended):

   • Use nvm: nvm install 20 && nvm use 20
   • Or download from nodejs.org

2. Use an older Astro version:

   npm install astro@4
   

License: MIT