Skip to main content

Cinephage Documentation UX Overhaul Design

Date: 2026-04-22 Scope: Complete user experience overhaul of the Cinephage documentation website Approach: B — Polished UX (medium effort, professional feel)

1. Goals​

  • Fix orphaned content (support/ section not in sidebar/footer)
  • Eliminate duplicate files (installation.md vs installation/index.md, faq.md vs faq/index.md)
  • Improve homepage visual impact and information density
  • Add search functionality
  • Create curated landing pages for each documentation section
  • Make the documentation feel professional, modern, and trustworthy
  • Integrate support content (FAQ, releases, roadmap) properly into the information architecture

2. Non-Goals​

  • Custom React components beyond basic cards and styling
  • Algolia DocSearch (using local search instead)
  • Blog section
  • Interactive deploy wizard enhancements (out of scope)
  • Multi-language support (i18n)

3. Current State Analysis​

Issues Found​

  • Orphaned content: docs/support/ exists with 10+ files but is not referenced in sidebars.ts or the footer
  • Duplicate files:
    • docs/getting-started/installation.md and docs/getting-started/installation/index.md
    • docs/support/faq.md and docs/support/faq/index.md
  • Sidebar: 100% autogenerated with no _category_.json files — no custom labels, collapsible behavior, or descriptions
  • Homepage: Bare-bones — title, one-line tagline, single CTA button
  • Docs landing page (docs/index.md): Wall of text with no visual hierarchy or card components
  • No search: No local or remote search configured
  • No breadcrumbs: Navigation depth not surfaced
  • Footer: Missing Support section entirely
  • Releases page: Hardcoded v0.5.0 only, won't reflect ongoing development (Cinephage has tags through v0.6.0-dev.6)

File Inventory​

  • 70+ markdown files across docs/
  • 5 top-level sections: getting-started/, guides/, reference/, explanation/, support/
  • Custom CSS: ~140 lines (mostly code block colors)
  • React components: HomepageFeatures, docker-configurator, compose

4. Design​

4.1 Sidebar & Navigation​

Principle: Keep 100% autogenerated for maintainability, but use _category_.json files for curation.

Changes:

  1. Add support/ category to sidebars.ts alongside existing sections
  2. Create _category_.json in each docs folder:
    • docs/getting-started/_category_.json
    • docs/guides/_category_.json
    • docs/reference/_category_.json
    • docs/explanation/_category_.json
    • docs/support/_category_.json
  3. Use sidebar_position frontmatter in all .md files for ordering within categories
  4. Set appropriate collapsed values per section (e.g., Getting Started expanded by default, Reference collapsed)
  5. Remove duplicate .md files that shadow index.md files:
    • Delete docs/getting-started/installation.md
    • Delete docs/support/faq.md

Example _category_.json for docs/support/:

{
  "label": "Support",
  "position": 5,
  "link": {
    "type": "generated-index",
    "title": "Support & Help",
    "description": "FAQ, release notes, roadmap, and troubleshooting resources for Cinephage."
  }
}

4.2 Support Section Overhaul​

Current state: 10+ files in docs/support/ with no sidebar entry.

Actions:

  1. Create docs/support/index.md — landing page with card grid:
    • FAQ card → /docs/support/faq
    • Releases card → /docs/support/releases
    • Roadmap card → /docs/support/roadmap
    • Troubleshooting card → /docs/guides/deploy/troubleshooting
  2. Keep faq/index.md as FAQ overview, delete duplicate faq.md
  3. Rewrite releases.md:
    • Title: "Release History"
    • Curated list of major versions with highlights
    • Table: Version | Date | Type (Stable/Preview) | GitHub Release Link
    • Auto-updating "Latest" badge concept (manual update, but prominent)
    • Docker tag reference table
    • Link to full GitHub changelog
  4. Keep roadmap.md as-is (already well-structured)
  5. Add sidebar_position to all support files for consistent ordering

4.3 Homepage Redesign (src/pages/index.tsx)​

Current: Title, tagline, single "Get Started" button.

New design:

  1. Hero section:
    • Title: "Cinephage" (or keep siteConfig.title)
    • Tagline: More compelling than current (e.g., "Self-hosted media management — unified")
    • Two CTAs: "Get Started" (primary, filled) + "View on GitHub" (secondary, outline)
    • Gradient background (reuse existing dark gradient)
  2. Feature cards section (enhance HomepageFeatures):
    • 6 cards in a grid: Movies, TV Shows, Indexers, Subtitles, Streaming, Live TV
    • Each card: Lucide/FontAwesome icon, title, 1-line description
    • Hover effect: subtle lift + shadow
  3. Clean footer spacing

4.4 Docs Landing Page (docs/index.md)​

Current: Long wall of text, no visual hierarchy.

New design:

  1. Welcome header — brief intro paragraph
  2. Card grid — 5 cards linking to major sections:
    • Getting Started (📚)
    • Guides (⚙️)
    • Reference (📖)
    • Explanation (💡)
    • Support (🆘)
  3. Quick Start — 3 numbered steps with icons:
    1. Install with Docker
    2. Configure TMDB API
    3. Add your first movie
  4. "New in v0.5.0" callout (Docusaurus admonition) highlighting major features
  5. Getting Help section with Discord + GitHub links

Use Docusaurus JSX-in-MDX capabilities for cards if available, or styled HTML divs.

4.5 Category Landing Pages​

Create or improve index.md for each section:

  1. getting-started/index.md — Installation → Setup → First Media
  2. guides/index.md — Three categories: Configure, Deploy, Use (with card grid)
  3. reference/index.md — API, Configuration, Database, YAML (with card grid)
  4. explanation/index.md — Architecture, Concepts, Design Decisions (with card grid)

Each landing page should:

  • Brief description of the section's purpose
  • Card grid or table of key pages with descriptions
  • Not just a file listing

4.6 Theming & CSS (src/css/custom.css)​

Add to existing CSS:

  1. Card grid styles:

    .card-grid {
      display: grid;
      grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
      gap: 1.5rem;
      margin: 2rem 0;
    }
    .card {
      border: 1px solid var(--ifm-color-emphasis-300);
      border-radius: 8px;
      padding: 1.5rem;
      transition: all 0.2s;
    }
    .card:hover {
      box-shadow: 0 4px 12px rgba(0,0,0,0.1);
      transform: translateY(-2px);
    }

  2. Admonition styling:

    • Info: blue tint matching primary color
    • Tip: green tint
    • Warning: amber tint
    • Danger: red tint
    • Ensure they work in both light and dark modes

  3. Table improvements:

    • Striped rows for readability
    • Better border contrast
    • Hover highlight on rows

  4. Mobile fixes:

    • Sidebar padding adjustments
    • Card grid single column on mobile
    • Hero text sizing for small screens

  5. Code block enhancements:

    • Copy button hover state
    • Better contrast for dark mode strings

4.7 Footer & Navbar​

Footer changes:

  • Add "Support" column with:
    • FAQ → /docs/support/faq
    • Troubleshooting → /docs/guides/deploy/troubleshooting
    • Roadmap → /docs/support/roadmap
    • Releases → /docs/support/releases

Navbar changes:

  • Add Discord icon/link (left side, near Documentation)
  • Integrate search bar (appears after adding search plugin)
  • Consider adding version badge or "Latest: v0.5.0" text

4.8 Search Integration​

  1. Install @docusaurus/plugin-search-local: 
    npm install @docusaurus/plugin-search-local
  2. Add to docusaurus.config.ts plugins array
  3. Configure indexing behavior (index docs only, exclude blog since it's disabled)
  4. Style search bar to match theme

4.9 Breadcrumbs & TOC​

  1. Enable breadcrumbs in themeConfig: 
    docs: {
      breadcrumbs: true
    }
  2. Set TOC depth to show h2-h3, hide h4+: 
    tableOfContents: {
      minHeadingLevel: 2,
      maxHeadingLevel: 3
    }

4.10 Information Architecture Cleanup​

  1. Remove duplicates:
    • docs/getting-started/installation.md
    • docs/support/faq.md
  2. Verify links: Run npm run build and ensure onBrokenLinks: 'throw' passes
  3. Standardize frontmatter: Every doc should have:
    • title
    • description
    • sidebar_position (for ordering)
    • Optional: tags, keywords

5. Files to Create/Modify​

New Files​

  • docs/superpowers/specs/2026-04-22-docs-ux-overhaul-design.md (this document)
  • docs/getting-started/_category_.json
  • docs/guides/_category_.json
  • docs/reference/_category_.json
  • docs/explanation/_category_.json
  • docs/support/_category_.json
  • docs/support/index.md
  • docs/getting-started/index.md (improve existing)
  • docs/guides/index.md (improve existing)
  • docs/reference/index.md (improve existing)
  • docs/explanation/index.md (improve existing)

Modified Files​

  • sidebars.ts — add support category
  • docusaurus.config.ts — add search plugin, breadcrumbs, TOC config, footer/navbar updates
  • src/pages/index.tsx — redesign homepage
  • src/pages/index.module.css — homepage styles
  • src/components/HomepageFeatures/index.tsx — enhance feature cards
  • src/components/HomepageFeatures/styles.module.css — card grid styles
  • src/css/custom.css — card, admonition, table, mobile styles
  • docs/index.md — rewrite docs landing page
  • docs/support/releases.md — rewrite release history
  • docs/support/roadmap.md — minor updates if needed
  • package.json — add search plugin dependency

Deleted Files​

  • docs/getting-started/installation.md
  • docs/support/faq.md

6. Testing & Verification​

  1. npm run build — must pass with no broken link errors
  2. Visual check:
    • Homepage renders correctly with feature cards
    • Sidebar shows all 5 categories including Support
    • Support landing page has card grid
    • Search bar appears in navbar
    • Breadcrumbs show on doc pages
    • Dark/light mode toggle works
    • Mobile view: sidebar accessible, cards stack vertically
  3. Link verification:
    • All internal links resolve
    • Footer links work
    • Navbar links work
    • Support section links work

7. Rollback Plan​

If issues arise:

  1. Revert sidebars.ts to original (remove support category)
  2. Restore deleted files from git if needed
  3. Revert docusaurus.config.ts changes
  4. Keep CSS additions (they're additive and won't break anything)

8. Future Considerations​

  • Algolia DocSearch: If site grows beyond ~100 pages or search performance degrades
  • Versioned docs: When v1.0 releases, consider Docusaurus versioning
  • Blog: Re-enable blog for release announcements
  • i18n: Spanish community exists, consider Spanish translation

Approved by: User Date: 2026-04-22