ADR-0002: Use Docsify for Documentation System
- Status:
- Superseded by ADR-0020: Switch to Zola for Documentation System
- Date: 2025-02-20
- History:
- 2024-11-03: Accepted
- 2025-02-20: Superseded by ADR-0020
- Tags: Documentation
Context
We need a documentation system that:
- Integrates well with our Git workflow
- Supports Markdown formatting
- Requires minimal setup and maintenance effort
- Is easy for developers to contribute to
- Can serve documentation directly from source control
Decision
We will use Docsify as our documentation system.
Consequences
Positive
- Git-native: Documentation lives directly in the repository as Markdown files
- Zero build process: Docsify generates documentation on the fly
- Markdown support: Developers can write documentation in familiar Markdown syntax
- Minimal setup: Only requires a single HTML file and basic configuration
- No static html files: Documentation is generated on-demand from Markdown
- Easy to maintain: No separate build pipeline or compilation step needed
- Good search capabilities out of the box
- Support for plugins and themes
Negative
- Requires JavaScript to be enabled in the browser
- No static HTML generation means reduced SEO capabilities
- Documentation loading might be slightly slower compared to pre-built static sites
- Limited compared to full-featured documentation systems like MkDocs or Sphinx
References
- ADR-0021: SPIKE Keeper as a Stateless Shard Holder
- ADR-0020: Switch to Zola for Documentation System
- ADR-0019: Plugin-Based Storage Backend Architecture
- ADR-0018: Administrative Access to SPIKE
- ADR-0017: Synchronous Persistence for SPIKE Secrets Store
- ADR-0016: Memory-First Secrets Store
- ADR-0015: Use Singular Form for File and Package Naming
- ADR-0014: Maintaining SQLite as SPIKE’s Primary Storage Backend
- ADR-0013: S3-Compatible Storage as SPIKE’s Backing Store
- ADR-0012: HTTP Methods for SPIKE API
- ADR-0011: PostgreSQL as SPIKE’s Backing Store
- ADR-0010: Session Token Storage Strategy for SPIKE Nexus
- ADR-0009: Multi-Administrator Support System
- ADR-0008: Administrative Access Control System
- ADR-0007: Root Key Lifecycle and Management Strategy
- ADR-0006: Trust Boundary Definition and Security Assumptions
- ADR-0005: Use SPIFFE mTLS for Inter-Component Authentication and Communication
- ADR-0004: SPIKE Keeper Minimalist Design Approach
- ADR-0003: Root Key Management and Storage Strategy
- ADR-0002: Use Docsify for Documentation System
- ADR-0001: Display Secrets in Plain Text in SPIKE Pilot Admin CLI