generated from nhcarrigan/template
This commit is contained in:
285
src/content/docs/projects/docs.md
Normal file
285
src/content/docs/projects/docs.md
Normal file
@ -0,0 +1,285 @@
|
|||||||
|
---
|
||||||
|
title: NHCarrigan Documentation Site
|
||||||
|
---
|
||||||
|
|
||||||
|
NHCarrigan Documentation Site (hereinafter the "Application") is a comprehensive documentation website built with Astro and Starlight that serves as the central hub for all documentation related to NHCarrigan's projects, policies, and services. The site provides organized access to technical documentation, legal policies, community guidelines, and project-specific information across multiple categories including Discord bots, web applications, libraries, and development tools. The Application features a custom-themed interface with accessibility considerations, analytics integration, and environmental sustainability features.
|
||||||
|
|
||||||
|
## 1. User Documentation
|
||||||
|
|
||||||
|
### Site Structure and Navigation
|
||||||
|
|
||||||
|
The Application is organized into several main sections accessible via the sidebar navigation:
|
||||||
|
|
||||||
|
- **About Us**: Mission statement, sustainability information, hiring, donations, contact, and mentorship
|
||||||
|
- **Legal Information**: Terms of service, privacy policy, software license, security policy, DMCA information, subprocessors list, and government actions
|
||||||
|
- **Community Policies**: Code of conduct, community guidelines, and appeal process
|
||||||
|
- **Development Documentation**: Contributing guide, contributor covenant, style guide, issue/PR labels, development environment, server setup, and VTubing setup
|
||||||
|
- **Project Documentation**: Comprehensive documentation for all NHCarrigan projects including Discord bots, web applications, libraries, and tools
|
||||||
|
- **Staff Guidelines**: Staff handbook and team application information
|
||||||
|
- **Miscellaneous Documents**: Additional resources like music management guides
|
||||||
|
|
||||||
|
### Key Features
|
||||||
|
|
||||||
|
#### Custom Theming
|
||||||
|
- Light and dark mode support with automatic detection
|
||||||
|
- Custom "Sakura Dreams" color scheme with pink/purple tones
|
||||||
|
- Accessibility features including OpenDyslexic font support
|
||||||
|
- Responsive design that works across all devices
|
||||||
|
|
||||||
|
#### Enhanced Footer
|
||||||
|
- TreeNation carbon offset widget integration for environmental sustainability
|
||||||
|
- Direct donation link for supporting the organization
|
||||||
|
- Standard Starlight navigation elements (edit links, last updated, pagination)
|
||||||
|
|
||||||
|
#### Analytics and Tracking
|
||||||
|
- Privacy-focused Plausible Analytics integration
|
||||||
|
- Page view and event tracking for user behavior insights
|
||||||
|
- Google AdSense integration for monetization
|
||||||
|
|
||||||
|
#### Content Features
|
||||||
|
- Project status badges indicating version and development status
|
||||||
|
- Comprehensive search functionality
|
||||||
|
- Table of contents for easy navigation within pages
|
||||||
|
- Social media links and contact information
|
||||||
|
|
||||||
|
### Accessibility
|
||||||
|
|
||||||
|
The Application includes several accessibility features:
|
||||||
|
- Semantic HTML structure with proper heading hierarchy
|
||||||
|
- OpenDyslexic font support for users with dyslexia
|
||||||
|
- High contrast color schemes
|
||||||
|
- Keyboard navigation support
|
||||||
|
- Screen reader compatible markup
|
||||||
|
|
||||||
|
## 2. Technical Documentation
|
||||||
|
|
||||||
|
### Architecture Overview
|
||||||
|
|
||||||
|
The Application is built using modern web technologies:
|
||||||
|
|
||||||
|
- **Framework**: Astro 5.3.0 - Static site generator for optimal performance
|
||||||
|
- **Theme**: Starlight 0.32.0 - Documentation-focused Astro integration
|
||||||
|
- **Language**: TypeScript 5.7.3 - Type-safe development
|
||||||
|
- **Build Tool**: Native Astro build system with minification and optimization
|
||||||
|
- **Package Manager**: PNPM (evidenced by pnpm-lock.yaml)
|
||||||
|
- **Hosting**: Static deployment to https://docs.nhcarrigan.com
|
||||||
|
|
||||||
|
### Project Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── components/ # Custom Astro components
|
||||||
|
│ ├── Footer.astro # Enhanced footer with TreeNation widget and donations
|
||||||
|
│ ├── ThemeProvider.astro # Custom theme system with analytics integration
|
||||||
|
│ └── navigation.ts # Sidebar navigation configuration
|
||||||
|
├── content/ # Documentation content
|
||||||
|
│ ├── config.ts # Content collection configuration
|
||||||
|
│ └── docs/ # Markdown/MDX documentation files
|
||||||
|
│ ├── intro.mdx # Homepage with hero section
|
||||||
|
│ ├── about/ # Organization information
|
||||||
|
│ ├── community/ # Community policies and guidelines
|
||||||
|
│ ├── dev/ # Development documentation
|
||||||
|
│ ├── legal/ # Legal policies and terms
|
||||||
|
│ ├── misc/ # Miscellaneous resources
|
||||||
|
│ ├── projects/ # Project-specific documentation
|
||||||
|
│ └── staff/ # Staff guidelines
|
||||||
|
├── fonts/ # Custom font files and CSS
|
||||||
|
├── pages/ # Astro pages
|
||||||
|
│ └── index.astro # Root page with legacy redirect handling
|
||||||
|
└── styles/ # Custom styling and themes
|
||||||
|
├── style.css # Global styles and CSS variables
|
||||||
|
├── theme.json # Light theme configuration for code highlighting
|
||||||
|
└── theme-dark.json # Dark theme configuration for code highlighting
|
||||||
|
|
||||||
|
public/ # Static assets
|
||||||
|
├── favicon.svg # Site favicon
|
||||||
|
├── logo.png # NHCarrigan logo
|
||||||
|
└── images/ # Project screenshots and documentation images
|
||||||
|
```
|
||||||
|
|
||||||
|
### Configuration Files
|
||||||
|
|
||||||
|
#### Astro Configuration (`astro.config.mjs`)
|
||||||
|
- Site URL configuration: https://docs.nhcarrigan.com
|
||||||
|
- Starlight integration with custom components
|
||||||
|
- Custom expressive code themes (Sakura Dreams light/dark)
|
||||||
|
- Analytics and tracking script injection
|
||||||
|
- TreeNation environmental widget integration
|
||||||
|
- Social media links and site metadata
|
||||||
|
- Custom CSS and font loading
|
||||||
|
|
||||||
|
#### Content Configuration (`src/content/config.ts`)
|
||||||
|
- Defines the `docs` collection using Starlight's schema
|
||||||
|
- Enables frontmatter validation and type safety
|
||||||
|
|
||||||
|
#### Navigation Configuration (`src/components/navigation.ts`)
|
||||||
|
- Hierarchical sidebar navigation structure
|
||||||
|
- Project status badges with version information
|
||||||
|
- External links to community resources
|
||||||
|
- Organized categorization of all documentation
|
||||||
|
|
||||||
|
### Custom Components
|
||||||
|
|
||||||
|
#### Footer Component (`src/components/Footer.astro`)
|
||||||
|
- Extends Starlight's default footer
|
||||||
|
- Integrates TreeNation carbon offset widget
|
||||||
|
- Adds donation link with visual call-to-action
|
||||||
|
- Maintains standard Starlight footer functionality (edit links, pagination, last updated)
|
||||||
|
|
||||||
|
#### Theme Provider (`src/components/ThemeProvider.astro`)
|
||||||
|
- Custom theme switching logic
|
||||||
|
- Analytics event tracking integration
|
||||||
|
- Theme persistence using localStorage
|
||||||
|
- Support for light, dark, and auto modes
|
||||||
|
|
||||||
|
### Styling System
|
||||||
|
|
||||||
|
#### CSS Variables and Theming
|
||||||
|
- Custom color scheme using CSS variables
|
||||||
|
- Pink/purple "Sakura Dreams" theme
|
||||||
|
- Dark mode with inverted color palette
|
||||||
|
- Background image integration for visual appeal
|
||||||
|
|
||||||
|
#### Typography
|
||||||
|
- OpenDyslexic font for accessibility
|
||||||
|
- Custom font loading via CSS @font-face
|
||||||
|
- Consistent typography hierarchy
|
||||||
|
|
||||||
|
### Development Workflow
|
||||||
|
|
||||||
|
#### Available Scripts
|
||||||
|
- `pnpm dev` / `pnpm start`: Development server on localhost:4321
|
||||||
|
- `pnpm build`: Production build to ./dist/
|
||||||
|
- `pnpm preview`: Preview production build locally
|
||||||
|
- `pnpm lint`: Spell checking with cspell
|
||||||
|
- `pnpm scan`: SonarCloud analysis for code quality
|
||||||
|
|
||||||
|
#### Code Quality
|
||||||
|
- TypeScript strict mode configuration
|
||||||
|
- ESLint integration (referenced in project documentation)
|
||||||
|
- SonarCloud integration for static analysis
|
||||||
|
- Spell checking for documentation content
|
||||||
|
|
||||||
|
### External Integrations
|
||||||
|
|
||||||
|
#### Analytics
|
||||||
|
- Plausible Analytics for privacy-focused tracking
|
||||||
|
- Custom event tracking for page views and interactions
|
||||||
|
- Google AdSense for monetization
|
||||||
|
|
||||||
|
#### Environmental Sustainability
|
||||||
|
- TreeNation carbon offset widget
|
||||||
|
- Environmental impact tracking and offsetting
|
||||||
|
|
||||||
|
#### Social and Community
|
||||||
|
- Links to self-hosted Git instance (git.nhcarrigan.com)
|
||||||
|
- Forum integration (forum.nhcarrigan.com)
|
||||||
|
- Mastodon instance (fedi.nhcarrigan.com)
|
||||||
|
- Matrix chat server (matrix.nhcarrigan.com)
|
||||||
|
- IRC server (irc.nhcarrigan.com)
|
||||||
|
|
||||||
|
### Performance and SEO
|
||||||
|
|
||||||
|
#### Static Site Generation
|
||||||
|
- Pre-built static pages for optimal loading speed
|
||||||
|
- Optimized asset delivery
|
||||||
|
- Compressed HTML output
|
||||||
|
|
||||||
|
#### SEO Features
|
||||||
|
- Open Graph meta tags for social media sharing
|
||||||
|
- Structured navigation for search engine crawling
|
||||||
|
- Sitemap generation (external: sitemap.nhcarrigan.com)
|
||||||
|
- Proper heading hierarchy and semantic markup
|
||||||
|
|
||||||
|
## 3. Legal Documentation
|
||||||
|
|
||||||
|
The Application serves as the central repository for all legal documentation related to NHCarrigan's operations and services. This includes:
|
||||||
|
|
||||||
|
### Comprehensive Legal Coverage
|
||||||
|
- **Terms of Service**: User agreements for all NHCarrigan services
|
||||||
|
- **Privacy Policy**: Data collection, processing, and user rights
|
||||||
|
- **Software License**: Open source licensing for projects
|
||||||
|
- **Security Policy**: Vulnerability reporting and security practices
|
||||||
|
- **DMCA and Copyright**: Intellectual property policies
|
||||||
|
- **Subprocessors List**: Third-party service providers and data processing
|
||||||
|
- **Government Actions**: Transparency reporting for legal requests
|
||||||
|
|
||||||
|
### Policy Management
|
||||||
|
- Centralized location for all legal documents
|
||||||
|
- Version control through Git for policy changes
|
||||||
|
- Public accessibility for transparency
|
||||||
|
- Regular updates reflecting current legal requirements
|
||||||
|
|
||||||
|
## 4. Contributing Documentation
|
||||||
|
|
||||||
|
### Development Environment Setup
|
||||||
|
|
||||||
|
#### Prerequisites
|
||||||
|
- Node.js (latest LTS version)
|
||||||
|
- PNPM package manager
|
||||||
|
- Git access to NHCarrigan's self-hosted instance
|
||||||
|
|
||||||
|
#### Local Development
|
||||||
|
1. Clone the repository from git.nhcarrigan.com
|
||||||
|
2. Install dependencies: `pnpm install`
|
||||||
|
3. Start development server: `pnpm dev`
|
||||||
|
4. Access local site at http://localhost:4321
|
||||||
|
|
||||||
|
### Content Contribution Guidelines
|
||||||
|
|
||||||
|
#### Documentation Standards
|
||||||
|
- Use Markdown (.md) or MDX (.mdx) for content files
|
||||||
|
- Follow established frontmatter schema for consistency
|
||||||
|
- Include appropriate metadata (title, description, etc.)
|
||||||
|
- Maintain consistent heading hierarchy (h2-h4 in table of contents)
|
||||||
|
|
||||||
|
#### File Organization
|
||||||
|
- Place content in appropriate `/src/content/docs/` subdirectories
|
||||||
|
- Use descriptive filenames following kebab-case convention
|
||||||
|
- Include project status badges for project documentation
|
||||||
|
- Update navigation configuration when adding new sections
|
||||||
|
|
||||||
|
#### Style Guidelines
|
||||||
|
- Follow existing documentation patterns
|
||||||
|
- Use clear, concise language
|
||||||
|
- Include code examples where appropriate
|
||||||
|
- Maintain accessibility standards
|
||||||
|
- Add project screenshots to `/public/images/` when relevant
|
||||||
|
|
||||||
|
### Code Contribution Process
|
||||||
|
|
||||||
|
#### Development Standards
|
||||||
|
- TypeScript strict mode compliance
|
||||||
|
- Pass spell checking with cspell
|
||||||
|
- Follow Astro and Starlight best practices
|
||||||
|
- Maintain existing component interfaces
|
||||||
|
|
||||||
|
#### Submission Process
|
||||||
|
1. Create feature branch from main
|
||||||
|
2. Make changes following style guidelines
|
||||||
|
3. Test locally with `pnpm dev`
|
||||||
|
4. Run quality checks: `pnpm lint`
|
||||||
|
5. Submit pull request to self-hosted Git instance
|
||||||
|
6. Await review and approval
|
||||||
|
|
||||||
|
#### Review Criteria
|
||||||
|
- Code quality and TypeScript compliance
|
||||||
|
- Documentation accuracy and completeness
|
||||||
|
- Accessibility compliance
|
||||||
|
- Performance impact assessment
|
||||||
|
- Security considerations
|
||||||
|
|
||||||
|
### Maintenance and Updates
|
||||||
|
|
||||||
|
#### Regular Maintenance Tasks
|
||||||
|
- Update project version badges
|
||||||
|
- Refresh project screenshots
|
||||||
|
- Review and update legal documents
|
||||||
|
- Monitor analytics for user behavior insights
|
||||||
|
- Update dependencies and security patches
|
||||||
|
|
||||||
|
#### Community Involvement
|
||||||
|
- Enable edit links for community contributions
|
||||||
|
- Maintain responsive support through various communication channels
|
||||||
|
- Encourage feedback through multiple contact methods
|
||||||
|
- Regular review of community guidelines and policies
|
||||||
Reference in New Issue
Block a user