Design guidelines help ensure consistency across our product. Initially, the team relied on Zeroheight for documentation but sought alternatives due to privacy concerns and licensing costs. They needed a self-hosted tool on Cisco's internal network with extensive customisation capabilities and collaborative editing features.
Choosing the Stack
Hugo emerged as the primary solution — a headless CMS that builds pages from Markdown files stored in Git repositories without requiring databases. Hugo is open-source and can be hosted on our own server, making it ideal for our requirements.
Hextra theme was chosen for the frontend. After researching available options, the team selected this clean, minimal theme with built-in shortcodes for tabs, collapsible sections, steppers, and callouts. It utilises the Tailwind CSS framework.
Decap CMS provided the backend solution. Described as the only open-source framework that can be self-hosted, it enabled team members to manage content through a user-friendly interface.
Technical Implementation
The implementation involved five key components:
- Maintained Hugo site functionality using Node.js with automatic rebuilds via webhook
- Integrated Hugo with Decap CMS through an enterprise GitHub account
- Configured an external OAuth provider for authentication
- Structured Decap CMS to align with frontend content architecture
- Developed custom widgets for specialised content needs (do's/don'ts and tables)
The project was challenging. "Usually, I would have given up if it took longer than expected. But this time, I was determined to see it through to the end." The completed design system now offers full control and customisation capabilities, with plans for additional refinements and team training.