Project date: 2026-08-30 Role: Architecture, implementation, validation and operation
A searchable Hugo and Git documentation platform containing 78 runbooks across ten categories and eight evidence-backed project case studies.
Environment and operating context#
The documentation began as university notes, moved through workplace OneNote collections and later into Obsidian. Each move improved parts of the organisation, but the information remained difficult to publish consistently, version alongside technical work and connect to related projects.
As the homelab expanded across Kubernetes, Microsoft 365, networking, security, virtualisation and recovery, documentation needed to become a maintained platform rather than a folder of notes.
Objective#
The goal was to create a searchable public technical reference that separated portfolio case studies from repeatable runbooks, retained Git history and enforced a boundary between publishable knowledge and restricted operational detail.
Operational value and risk reduction#
Before: Knowledge was fragmented across university notes, OneNote and Obsidian, with inconsistent structure and weak linkage to implementation evidence.
After: A searchable Git-backed Hugo site contains 78 runbooks across ten categories and eight evidence-backed case studies.
Risk reduced: Operational knowledge is less dependent on one note application or memory, while public-safety rules keep restricted material out of the published site.
Architectural decisions and alternatives#
- Continue with OneNote
- Convenient for notes, but weaker for Git history, static publishing and content-as-code workflows.
- Continue with Obsidian only
- Strong local knowledge management, but public publishing and theme integration required additional workflow.
- Hosted documentation SaaS
- Could reduce maintenance, but offers less control and does not align as closely with the self-hosted portfolio objective.
- Selected design
- Hugo and Blowfish provide fast static output, Git-controlled source, search, aliases and a clear public/private boundary.
Technical challenges#
The source material varied in age, structure and purpose. University learning notes, workplace procedures and homelab runbooks could not simply be published unchanged. Content needed common metadata, category ownership, public-safety review, aliases for moved pages and a design that worked on desktop and mobile.
Proposed solution#
Hugo Extended 0.165.0 generates the site using the Blowfish theme. Home output includes HTML, RSS and JSON, enabling built-in search. Authored Markdown or HTML remains the source; the generated public directory is build output. Projects explain engineering decisions and outcomes, while Lab Notes contain operational procedures.
Information architecture#
| Runbook source files | 78 |
| Runbook categories | 10 |
| Individual project case studies | 8 |
| Generated pages | 341 |
| Aliases | 113 |
| Hugo build time | 2.645 seconds |
| Search | Enabled |
| Theme | Blowfish |
- Windows: 17 documents
- GitOps: 9
- Microsoft 365: 9
- Networking: 9
- Kubernetes: 7
- Linux: 7
- Security: 6
- macOS: 5
- Monitoring: 5
- Virtualisation: 3
Implementation#
The website provides Home, About, Journey, Projects, Homelab and Runbook navigation. Category landing pages organise the 78 runbooks, project pages link to supporting procedures, and Hugo generates tables of contents, metadata, aliases and search data.
The eight project articles were rewritten because the original pages had correct layout but insufficient engineering evidence. The revised standard includes context, objectives, constraints, architecture, responsibilities, implementation, validation, measurable outcomes and lessons learned.
Content governance#
- Git-controlled authored source
- Generated HTML not edited directly
- Public, internal and restricted information separated
- No credentials, private keys or raw security events
- Claims classified as implemented, validated, observed, documented or planned
- No fabricated customer testimonials or commercial KPIs
- Runbooks linked to the projects they support
Validation and measurable outcomes#
A clean Hugo build generated 341 pages, three paginator pages, seven static files and 113 aliases with no reported build error. Search is enabled in the active configuration, the public base URL is https://lintech.uk/, and the source is organised into ten practical categories.
Outcome#
The documentation is now a versioned, searchable technical platform rather than material tied to one note-taking application. It presents both breadth, through 78 runbooks, and depth, through evidence-backed project case studies.
Skills demonstrated#
- Technical writing and information architecture
- Hugo and Blowfish
- Metadata, search and aliases
- Git-based content management
- Public-safety review
- Runbook and case-study design
Lessons learned#
More documentation is not automatically better documentation. A useful knowledge platform needs clear audiences, evidence standards, lifecycle status and a deliberate distinction between narrative case studies and executable procedures.
Current status and next steps#
Maintained and in pre-release content remediation. The next step is final route, link and responsive testing before the redesigned site replaces the existing public website.
Explore the work#
Browse the runbook library or view all project case studies.
How it was done#
- Consolidated the source material. Notes that had moved from university documents to workplace OneNote and then Obsidian were reviewed and moved into a Git-controlled website repository.
- Separated content types. Projects were defined as engineering narratives covering decisions and outcomes, while Lab Notes became operational runbooks focused on repeatable procedures.
- Created the taxonomy. Runbooks were organised into GitOps, Kubernetes, Linux, macOS, Microsoft 365, Monitoring, Networking, Security, Virtualisation and Windows categories.
- Selected the publishing platform. Hugo Extended and the Blowfish theme were used to generate a fast static site with responsive layouts, taxonomies, tables of contents, aliases and JSON search output.
- Standardised article metadata. Titles, summaries, dates, categories, tags, publication status and related links were made consistent so content could be discovered and maintained.
- Established public-safety rules. Credentials, private keys, raw security events and overly specific recovery details remain outside the public site. Internal documentation stays in private repositories.
- Preserved moved URLs. Hugo aliases were used to retain navigation paths as material changed location, reducing broken links during the migration.
- Enabled search and navigation. Home output includes JSON for search, and custom desktop and mobile navigation provides direct access to Projects, Homelab and Runbooks.
- Reworked the project portfolio. Eight short placeholder pages were replaced with evidence-backed case studies that include context, process, validation, measurable outcomes and lessons learned.
- Validated the build. A clean Hugo build generated 341 pages, three paginator pages, seven static files and 113 aliases in 2.645 seconds without a reported build failure.
Evidence methodology#
The figures in this case study were derived from reproducible source and runtime checks rather than estimates.
- Runbook and project totals were counted from authored files under content/lab-notes and content/projects, excluding generated public output.
- Category totals were calculated from the ten top-level Lab Notes directories.
- A clean Hugo build supplied the generated page, alias and duration evidence.
Limitations and residual risks#
- The redesigned site remains pre-release until final content and deployment validation are complete.
- File and page counts measure scope, not documentation quality.
- Public runbooks intentionally omit sensitive internal detail.
- Documentation can become stale and still requires review after platform changes.
Plain-English glossary#
- Hugo
- A static-site generator that builds deployable pages from content and templates.
- Alias
- A generated redirect that preserves access to a page after its URL changes.
- Content as code
- Managing documentation through source files, version control and repeatable builds.
Independent validation#
This was a self-directed engineering project rather than a client engagement. Credibility is established through deployed configuration, source history, successful builds, operational measurements, restoration tests and repeatable validation rather than a client testimonial.