ADR-001: Enable Docs Plugin for Technical Documentation

Status	Proposed
Date	2026-01-01
Decision Makers	Christopher Joseph
Technical Story	Enable structured navigation for ADRs to demonstrate architectural thinking to recruiters

Summary

Enable the Docusaurus docs plugin at /docs to host Architecture Decision Records (ADRs) and technical documentation, while preserving the blog-first homepage architecture.

Context and Problem Statement

The amiable.dev site currently operates as a blog-first Docusaurus site with the docs plugin disabled (docs: false). As the project matures, there's a need to:

1. Store Architecture Decision Records (ADRs) in a structured, navigable format
2. Provide technical documentation for projects and contributions
3. Maintain the blog-first user experience while adding documentation capabilities

The docs folder already contains content (docs/contributing/ai-attribution.md, tutorial scaffolding) that is not being served due to the disabled plugin.

Decision Drivers

• Engineer accessibility: ADRs and technical docs should be easily discoverable and navigable
• Recruiter visibility: Demonstrate technical decision-making and architectural thinking
• Maintainability: Leverage Docusaurus's built-in docs features (sidebar, search)
• Linkability: ADRs should have stable, predictable URLs for external reference
• SEO: Proper routing and metadata for documentation content
• Minimal disruption: Preserve existing blog-first architecture and URLs

Non-Goals (Phase 1)

• Versioning: Not needed for ADRs; may revisit if project docs require it
• Multi-instance docs: Single docs instance is sufficient for current scope
• Full search integration: Will use Docusaurus default search; Algolia can be evaluated later

Considered Options

Option 1: Enable Docs Plugin at /docs (Recommended)

Re-enable the docs plugin with default routing at /docs, keeping blog at root.

Configuration change:

docs: {
  sidebarPath: './sidebars.js',
  editUrl: 'https://github.com/amiable-dev/amiable-docusaurus/edit/main/',
},

Pros:

• Clean URL separation (/ for blog, /docs for documentation)
• Standard Docusaurus pattern, well-documented
• Automatic sidebar generation
• Preserves all existing blog URLs

Cons:

• Requires navbar update to add link
• Need to clean up tutorial scaffolding content

Option 2: Multi-instance Docs Plugin

Use multiple docs plugin instances for different content types (ADRs, guides, etc.).

Pros:

• Separate routing per content type (/adrs, /guides)
• Independent sidebars and versioning

Cons:

• Added complexity for current needs
• Over-engineering for initial requirements

Option 3: Keep Docs Disabled, Use Blog for Everything

Continue with blog-only approach, publishing ADRs as blog posts.

Pros:

• No configuration changes needed
• Unified content model

Cons:

• ADRs buried in chronological blog feed
• No structured navigation for technical docs
• Poor discoverability for recruiters/engineers

Decision Outcome

Chosen option: Option 1 - Enable Docs Plugin at /docs

This provides a clean separation between temporal content (blog) and reference content (docs/ADRs) while maintaining the blog-first architecture.

Implementation Plan

Phase 1: Content Cleanup (Before Enabling)

1. Delete or set draft: true on all tutorial scaffolding content to prevent indexing incomplete pages
2. Ensure ADR content is ready before enabling the plugin

Phase 2: Configuration Update

1. Update docusaurus.config.js to enable docs:

   docs: {
     path: 'docs',
     routeBasePath: 'docs',
     sidebarPath: './sidebars.js',
     editUrl: 'https://github.com/amiable-dev/amiable-docusaurus/edit/main/',
   },

2. Create sidebars.js with hybrid approach (curated top-level, auto-generated sections):

   module.exports = {
     docs: [
       'intro',
       {
         type: 'category',
         label: 'Architecture Decisions',
         link: {
           type: 'generated-index',
           description: 'Key technical decisions and their rationale.',
         },
         items: [{type: 'autogenerated', dirName: 'adrs'}],
       },
       {
         type: 'category',
         label: 'Contributing',
         items: [{type: 'autogenerated', dirName: 'contributing'}],
       },
     ],
   };

3. Add navbar item with recruiter-friendly label:

   {to: '/docs', label: 'Architecture', position: 'left'},

Phase 3: Landing Page

Create /docs/intro.md as a "Start Here" page explaining:

• What ADRs are and why they matter
• Highlighted decisions (2-3 key ADRs)
• How to navigate the documentation

Phase 4: Validation

1. Update CLAUDE.md to reflect docs being enabled
2. Run yarn build and verify no broken links
3. Test navigation between blog and docs
4. Verify search indexes documentation content

Consequences

Positive

• ADRs are discoverable via navigation and search
• Clean content separation (blog for posts, docs for reference)
• Foundation for future documentation (project guides, API docs)
• Demonstrates technical rigor to recruiters
• Stable, linkable URLs for ADRs

Negative

• Additional navbar item (mitigated by clear labeling)
• Need to maintain sidebar configuration as docs grow
• Ongoing commitment to keep documentation current

Risks

Risk	Likelihood	Impact	Mitigation
Legacy content leak (tutorial scaffolding indexed)	Medium	Low	Delete scaffolding before enabling; verify with yarn build
Empty docs section looks unfinished	Medium	Medium	Launch with 3+ ADRs and intro page
Broken internal links	Low	Medium	Run link validation in Phase 4

Success Metrics

• ADR pages receive measurable traffic within 3 months
• Recruiters mention ADRs or architecture section in interviews
• Engineers can navigate to relevant ADRs from blog posts

Related Decisions

• ADR-002: GitHub Projects Showcase (will link to ADRs and documentation)