Zcash Modern Doc
A modern Zcash documentation
The problem Zcash Modern Doc solves
Project Overview: Modern Zcash Documentation Portal
Repository: https://github.com/Zackmendel/zcash_docs
The Problem it Solves
The Zcash ecosystem is built on cutting-edge privacy technology, yet the existing documentation portal (hosted on ReadTheDocs via Sphinx) felt disconnected from the modern developer experience.
The primary problem was an Information Accessibility and UX Gap.
While the technical content of the original documentation is robust, the presentation layer suffered from:
- Dated Interface: The legacy Sphinx theme lacked visual hierarchy, making it difficult for new developers to scan for relevant information quickly.
- Poor Mobile Experience: Navigation on mobile devices was cumbersome, discouraging on-the-go reading or quick reference checks.
- Slow Search: Default static site searches often lag; developers expect instant, "Cmd+K" style command palettes.
- Rigid Contribution Flow: The reliance on reStructuredText (.rst) creates friction for modern web developers who are accustomed to Markdown (.md) and component-driven documentation.
How this Project Helps
This project rebuilds the Zcash documentation interface using a modern tech stack (Next.js & Tailwind), solving these issues by providing:
- App-Like Navigation: A Single Page Application (SPA) feel where navigating between topics is instant, without full page reloads.
- Enhanced Readability: A careful focus on typography, contrast (Dark Mode by default), and spacing to reduce cognitive load when reading complex cryptographic concepts.
- Responsive Design: A fully fluid layout that adapts the sidebar and content for tablets and phones, making the docs accessible anywhere.
- Unified Format: By implementing a conversion pipeline to Markdown, we pave the way for a future where docs can be maintained using standard MDX, allowing for interactive components (like live RPC code blocks) directly within the documentation.
Challenges I ran into
Challenges I Ran Into
Rebuilding a documentation site for a protocol as complex as Zcash was not just a matter of copying text. We encountered significant hurdles regarding data formats and build pipelines.
1. The "RST vs. Markdown" War & Data Loss
The original Zcash repository relies heavily on reStructuredText (.rst), but the modern React ecosystem thrives on Markdown.
- The Hurdle: I initially wrote a script to convert .rst files using Pandoc. However, I discovered that the source repo was a "hybrid"—it contained both .rst and .md files. My script was strictly looking for .rst, resulting in a deployed site with missing pages and broken links.
- The Solution: I engineered a robust Bash pipeline that iterates through the source directory recursively. It now detects the file extension and applies conditional logic: if it is .rst, it pipes it through Pandoc for conversion; if it is .md, it preserves the content. Crucially, it injects YAML Frontmatter (metadata) into both types so Next.js can generate the sidebar dynamically.
2. Next.js App Router: Server vs. Client Separation
Migrating to the Next.js 14+ App Router required a mental shift.
- The Hurdle: I attempted to import the documentation data directly into the UI components. Since the UI required state (for the mobile menu and search filtering), it had to be a Client Component. However, Client Components cannot directly read from the file system (fs).
- The Solution: I architected a strict separation of concerns.
- Server Side: A lib/docs.ts utility handles the heavy lifting—reading the file system, parsing Frontmatter, and rendering Markdown strings.
- Client Side: The DocsClient.tsx receives this pre-digested data as props. This ensures the site is SEO-friendly (content rendered on the server) but interactive (navigation on the client).
Tracks Applied (4)
Privacy Infrastructure & Developer Tools
Zcash Community Grants
Privacy Infrastructure & Developer Tools
Raybot
Generic Bounty
Mintlify
General Bounty
Project Tachyon
Technologies used