@amiable-dev/docusaurus-plugin-stentorosaur 0.14.0 → 0.14.2

package/QUICKSTART.md

@@ -25,7 +25,7 @@ Create a Personal Access Token at <https://github.com/settings/tokens> with `rep
 > - Without a token, the plugin shows **demo data** (useful for testing)
 > - See the [README](./README.md#github-token-setup) for detailed token setup
 
-## Step 2: Configure Docusaurus
+## Step 3: Configure Docusaurus
 
 Add to your `docusaurus.config.js`:
 
@@ -43,7 +43,7 @@ module.exports = {
           { name: 'database', type: 'system' },
         ],
         token: process.env.GITHUB_TOKEN,
-        
+
         // Optional: Choose status page layout
         statusView: 'upptime',  // 'default' | 'upptime'
 
@@ -58,7 +58,7 @@ module.exports = {
 };
 ```
 
-## Step 3: Set up GitHub Actions
+## Step 4: Set up GitHub Actions
 
 The plugin uses three workflows that work together:
 
@@ -92,6 +92,7 @@ cp node_modules/@amiable-dev/docusaurus-plugin-stentorosaur/templates/workflows/
 ```
 
 **What it does:**
+
 - ✅ Checks endpoints every 5 minutes
 - ✅ Updates `current.json` with response times and status
 - ✅ Creates GitHub Issues for critical failures
@@ -106,6 +107,7 @@ cp node_modules/@amiable-dev/docusaurus-plugin-stentorosaur/templates/workflows/
 ```
 
 **What it does:**
+
 - ✅ Runs when issues are created/updated/closed
 - ✅ Runs hourly to catch any changes
 - ✅ Generates `incidents.json` from issues with `status` label
@@ -141,12 +143,14 @@ cp node_modules/@amiable-dev/docusaurus-plugin-stentorosaur/templates/workflows/
 ```
 
 **deploy.yml** - Immediate deployments:
+
 - ✅ Triggered by code pushes to main
 - ✅ Triggered by `repository_dispatch` events (critical incidents)
 - ✅ Ignores monitoring data commits (via `paths-ignore`)
 - ✅ Deploys within ~2 minutes for critical incidents
 
 **deploy-scheduled.yml** - Scheduled deployments:
+
 - ✅ Runs every hour (configurable)
 - ✅ Picks up non-critical incident updates
 - ✅ Picks up maintenance window changes
@@ -154,7 +158,7 @@ cp node_modules/@amiable-dev/docusaurus-plugin-stentorosaur/templates/workflows/
 
 **Smart Deployment Logic:**
 
-```
+```text
 Critical Incident:
   Issue created with 'critical' + 'status' labels
     → status-update.yml runs
@@ -183,7 +187,7 @@ Monitoring Data:
 
 After copying all workflows, you'll have:
 
-```
+```text
 .github/
   workflows/
     monitor-systems.yml      # Every 5 min - Check endpoints, update current.json
@@ -195,14 +199,14 @@ After copying all workflows, you'll have:
 
 **Data Flow:**
 
-```
+```text
 Every 5 min:
   monitor-systems.yml → current.json → [skip ci] → No deploy
-  
+
 Critical failure:
   monitor-systems.yml → Creates Issue → status-update.yml
     → incidents.json → repository_dispatch → deploy.yml → IMMEDIATE DEPLOY
-  
+
 Non-critical issue:
   GitHub Issue created → status-update.yml
     → incidents.json → [skip ci] → deploy-scheduled.yml (hourly) → DEPLOY
@@ -219,7 +223,7 @@ mkdir -p .github/ISSUE_TEMPLATE
 cp node_modules/@amiable-dev/docusaurus-plugin-stentorosaur/templates/ISSUE_TEMPLATE/status-issue.yml .github/ISSUE_TEMPLATE/
 ```
 
-## Step 4: Create Your First Status Issue
+## Step 5: Create Your First Status Issue
 
 Create a new GitHub issue with these labels:
 
@@ -246,9 +250,9 @@ Scheduled database upgrade to improve performance.
 
 **Labels for maintenance:** `maintenance`, `api`, `database` (affected entities)
 
-💡 **Tip:** You can use simple entity labels (`api`) or namespaced (`system:api`). Both work!
+Tip: You can use simple entity labels (`api`) or namespaced (`system:api`). Both work!
 
-## Step 5: View Your Status Page
+## Step 6: View Your Status Page
 
 Start your Docusaurus dev server:
 
@@ -265,6 +269,7 @@ Navigate to: `http://localhost:3000/status`
 Pick the layout that works best for you:
 
 **Default Layout** - Compact design with services and incidents:
+
 ```javascript
 {
   statusView: 'default',  // or omit (this is the default)
@@ -272,6 +277,7 @@ Pick the layout that works best for you:
 ```
 
 **Upptime Layout** - Structured sections with maintenance support:
+
 ```javascript
 {
   statusView: 'upptime',
@@ -305,6 +311,7 @@ Create maintenance issues with special formatting:
 **Affected Systems:** api, database
 
 ## Description
+
 Database upgrade to improve performance.
 ```
 
@@ -350,7 +357,7 @@ import ChartPanel from '@theme/ChartPanel';
 
 # API Monitoring
 
-<ChartPanel 
+<ChartPanel
   systemName="api"
   showCharts={['response', 'uptime', 'sli', 'errorBudget']}
   defaultPeriod="7d"
@@ -395,7 +402,7 @@ entities: [
 ]
 ```
 
-**Note:** The Entity model supports multiple types beyond just systems: `system`, `process`, `project`, `event`, `sla`, `custom`.
+Note: The Entity model supports multiple types beyond just systems: `system`, `process`, `project`, `event`, `sla`, `custom`.
 
 ### Embed Status Components
 
@@ -428,6 +435,6 @@ import ChartPanel from '@theme/ChartPanel';
 
 ## Need Help?
 
-- 📖 Read the [full documentation](README.md)
-- 🐛 [Report an issue](https://github.com/your-org/docusaurus-plugin-stentorosaur/issues)
-- 💬 [Join discussions](https://github.com/your-org/docusaurus-plugin-stentorosaur/discussions)
+- Read the [full documentation](README.md)
+- [Report an issue](https://github.com/amiable-dev/docusaurus-plugin-stentorosaur/issues)
+- [Join discussions](https://github.com/amiable-dev/docusaurus-plugin-stentorosaur/discussions)

package/README.md

@@ -61,7 +61,7 @@ npm install @amiable-dev/docusaurus-plugin-stentorosaur
 yarn add @amiable-dev/docusaurus-plugin-stentorosaur
 ```
 
-> **📚 Recommended**: Use an orphaned `status-data` branch for storing monitoring data (following the Upptime pattern). This keeps your main branch lean and improves performance. See [Orphaned Branch Setup Guide](./ORPHANED_BRANCH_SETUP.md) for setup instructions.
+> **📚 Recommended**: Use an orphaned `status-data` branch for storing monitoring data (following the Upptime pattern). This keeps your main branch lean and improves performance. See [Orphaned Branch Setup Guide](./docs/setup/ORPHANED_BRANCH_SETUP.md) for setup instructions.
 
 ## GitHub Token Setup
 
@@ -879,7 +879,7 @@ cp node_modules/@amiable-dev/docusaurus-plugin-stentorosaur/templates/workflows/
 # Configure your endpoints in monitor-systems.yml
 ```
 
-See [MONITORING_SYSTEM.md](./MONITORING_SYSTEM.md) for complete documentation.
+See [MONITORING_SYSTEM.md](./docs/reference/MONITORING_SYSTEM.md) for complete documentation.
 
 ### Three-File Data Architecture
 
@@ -992,7 +992,7 @@ npx stentorosaur-update-status --write-incidents --write-maintenance --verbose
 npx stentorosaur-update-status --output-dir ./public/status --write-incidents --write-maintenance
 ```
 
-See [CONFIGURATION.md](./CONFIGURATION.md) for CLI option details.
+See [CONFIGURATION.md](./docs/reference/CONFIGURATION.md) for CLI option details.
 
 ## Status Data Storage Patterns
 
@@ -1225,7 +1225,7 @@ jobs:
 }
 ```
 
-See [CONFIGURATION.md](./CONFIGURATION.md) for detailed examples.
+See [CONFIGURATION.md](./docs/reference/CONFIGURATION.md) for detailed examples.
 
 ## How It Works
 
@@ -1542,7 +1542,7 @@ Send real-time alerts to Slack, Telegram, Email, or Discord when incidents occur
 
 **Supported Channels:** Slack, Telegram, Email (SMTP), Discord
 
-**📖 Complete Guide**: See [NOTIFICATIONS.md](./NOTIFICATIONS.md) for setup instructions, configuration examples, and troubleshooting.
+**📖 Complete Guide**: See [NOTIFICATIONS.md](./docs/reference/NOTIFICATIONS.md) for setup instructions, configuration examples, and troubleshooting.
 
 ## Best Practices
 
@@ -1600,7 +1600,7 @@ Contributions are welcome! Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for d
 
 - **Issues**: [GitHub Issues](https://github.com/amiable-dev/docusaurus-plugin-stentorosaur/issues)
 - **Discussions**: [GitHub Discussions](https://github.com/amiable-dev/docusaurus-plugin-stentorosaur/discussions)
-- **Documentation**: See [CONFIGURATION.md](./CONFIGURATION.md) for detailed examples
+- **Documentation**: See [CONFIGURATION.md](./docs/reference/CONFIGURATION.md) for detailed examples
 
 ## License
 

package/docs/README.md

@@ -0,0 +1,122 @@
+# Documentation Index
+
+This directory contains comprehensive documentation for the Docusaurus Status Plugin (Stentorosaur).
+
+## Quick Access
+
+**New to the project?** Start with the root-level documentation:
+- [README.md](../README.md) - Project overview and installation
+- [QUICKSTART.md](../QUICKSTART.md) - Get started in 5 minutes
+- [CONTRIBUTING.md](../CONTRIBUTING.md) - How to contribute
+- [CHANGELOG.md](../CHANGELOG.md) - Version history
+
+## Directory Structure
+
+### `/architecture` - System Design Documentation
+
+Understanding how the plugin works internally:
+
+- [ARCHITECTURE-INDEX.md](./architecture/ARCHITECTURE-INDEX.md) - Overview of architectural documentation
+- [ARCHITECTURE-SUMMARY.md](./architecture/ARCHITECTURE-SUMMARY.md) - High-level system design
+- [ARCHITECTURE-ANALYSIS.md](./architecture/ARCHITECTURE-ANALYSIS.md) - Detailed technical analysis
+
+**When to read:** Understanding internal design, making architectural decisions, or contributing significant features.
+
+### `/setup` - Advanced Setup Guides
+
+Step-by-step guides for specific deployment scenarios:
+
+- [ORPHANED_BRANCH_SETUP.md](./setup/ORPHANED_BRANCH_SETUP.md) - Upptime-style status-data branch configuration
+- [TRUSTED_PUBLISHING_SETUP.md](./setup/TRUSTED_PUBLISHING_SETUP.md) - npm OIDC publishing configuration
+- [PUBLISHING.md](./setup/PUBLISHING.md) - Release and publishing workflow
+
+**When to read:** Setting up production deployments, configuring CI/CD, or preparing for release.
+
+### `/reference` - Feature Documentation
+
+Detailed documentation for specific features:
+
+- [CONFIGURATION.md](./reference/CONFIGURATION.md) - Complete configuration options reference
+- [TESTING.md](./reference/TESTING.md) - Testing strategy and guidelines
+- [MONITORING_SYSTEM.md](./reference/MONITORING_SYSTEM.md) - Automated monitoring architecture
+- [NOTIFICATIONS.md](./reference/NOTIFICATIONS.md) - Real-time notification system (Slack, Telegram, Email, Discord)
+
+**When to read:** Implementing specific features, configuring advanced options, or troubleshooting.
+
+### `/archive` - Historical Documentation
+
+Legacy documentation preserved for reference:
+
+- [CODE-REFERENCE-GUIDE.md](./archive/CODE-REFERENCE-GUIDE.md) - Legacy code navigation guide
+- [PROJECT_SUMMARY.md](./archive/PROJECT_SUMMARY.md) - Original project summary (superseded by README)
+- [NOTIFICATION-SYSTEM-SUMMARY.md](./archive/NOTIFICATION-SYSTEM-SUMMARY.md) - Notification implementation notes
+- [UPPTIME_CONFIGURATION_COMPARISON.md](./archive/UPPTIME_CONFIGURATION_COMPARISON.md) - Upptime vs Stentorosaur comparison
+
+**When to read:** Historical context, understanding legacy design decisions, or migration reference.
+
+## Documentation by Use Case
+
+### I want to...
+
+**Get started quickly**
+→ [QUICKSTART.md](../QUICKSTART.md)
+
+**Understand what the plugin does**
+→ [README.md](../README.md)
+
+**Configure all available options**
+→ [docs/reference/CONFIGURATION.md](./reference/CONFIGURATION.md)
+
+**Set up automated monitoring**
+→ [docs/reference/MONITORING_SYSTEM.md](./reference/MONITORING_SYSTEM.md)
+
+**Add notification alerts**
+→ [docs/reference/NOTIFICATIONS.md](./reference/NOTIFICATIONS.md)
+
+**Deploy to production with GitHub Pages**
+→ [README.md#github-actions-setup](../README.md#github-actions-setup)
+
+**Use an orphaned branch for status data**
+→ [docs/setup/ORPHANED_BRANCH_SETUP.md](./setup/ORPHANED_BRANCH_SETUP.md)
+
+**Contribute to the project**
+→ [CONTRIBUTING.md](../CONTRIBUTING.md)
+
+**Understand the architecture**
+→ [docs/architecture/ARCHITECTURE-INDEX.md](./architecture/ARCHITECTURE-INDEX.md)
+
+**Write tests**
+→ [docs/reference/TESTING.md](./reference/TESTING.md)
+
+**Publish a new version**
+→ [docs/setup/PUBLISHING.md](./setup/PUBLISHING.md)
+
+## Maintenance
+
+### Keeping Documentation Current
+
+Documentation should be updated whenever:
+- ✅ New features are added
+- ✅ Configuration options change
+- ✅ Workflows are modified
+- ✅ Breaking changes occur
+- ✅ Best practices evolve
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for guidelines on updating documentation.
+
+### Documentation Standards
+
+All documentation in this repository follows these standards:
+
+1. **Markdown Format** - GitHub-flavored markdown
+2. **Clear Headers** - Hierarchical structure with descriptive titles
+3. **Code Examples** - Working examples for all features
+4. **Cross-References** - Links to related documentation
+5. **Version Context** - Note when features were added (e.g., "v0.5.0+")
+6. **Current State** - Reflect the actual implementation, not future plans
+
+## Need Help?
+
+- **Issues**: [GitHub Issues](https://github.com/amiable-dev/docusaurus-plugin-stentorosaur/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/amiable-dev/docusaurus-plugin-stentorosaur/discussions)
+- **Support**: See [SUPPORT.md](../SUPPORT.md)