aster.cloud aster.cloud
  • /
  • Platforms
    • Public Cloud
    • On-Premise
    • Hybrid Cloud
    • Data
  • Architecture
    • Design
    • Solutions
    • Enterprise
  • Engineering
    • Automation
    • Software Engineering
    • Project Management
    • DevOps
  • Programming
  • Tools
  • About
aster.cloud aster.cloud
  • /
  • Platforms
    • Public Cloud
    • On-Premise
    • Hybrid Cloud
    • Data
  • Architecture
    • Design
    • Solutions
    • Enterprise
  • Engineering
    • Automation
    • Software Engineering
    • Project Management
    • DevOps
  • Programming
  • Tools
  • About
  • Engineering

Fast And Effective Tools For CNCF And Open Source Project Websites

  • relay
  • January 29, 2023
  • 3 minute read

Why some top-velocity projects use Hugo and Docsy to publish technical documentation

Some of CNCF’s top-velocity projects — such as Kubernetes, OpenTelemetry and gRPC — use Hugo as their static website generator. Why? Because Hugo is feature-rich, flexible, and fast — even for large sites.

How fast? It takes Hugo less than 30 seconds* to generate the 5600+ pages of technical documentation (written in 15 natural languages) of the kubernetes.io website, providing a delightful experience for all contributors.

Docsy: a theme for technical documentation

Most Hugo-enabled CNCF projects use the Docsy Hugo theme because it provides key features in support of publishing technical documentation that is easy to navigate, search, and contribute to. Out-of-the-box, Docsy provides support for these key features, and more:

  • Multilingual and multi-versioned documentation
  • Breadcrumbs, auto-generated doc-navigation and in-page table of contents
  • Site search
  • In-page view-page-source and page-edit links — making it easy for one-time contributors to submit minor changes like typo fixes.

By using a theme like Docsy, CNCF projects (1) can get their technical documentation online more quickly with the core features listed above (fast initial setup), and (2) let their technical writers and community members focus on creating and maintaining content, rather than creating/fixing site layouts, style files, and Hugo template code.

Docsy was open sourced by Google in 2019. Its creation, from a year or so earlier, was motivated by a pressing demand — from the over 2000 open source projects at Google — to make it easier for projects to publish their documentation. Use of Docsy continues to grow at Google (with protobuf.dev most recently being converted to use Docsy), the CNCF, and elsewhere.

Read More  Google Cloud Next 2019 | Preventing Data Exfiltration on GCP

Contributing to Docsy

As a member of the CNCF techdocs team, I have been contributing to Docsy for the past two years. Initially, I upstreamed fixes made to Docsy while working on gRPC.io — such as this homepage/top-nav style improvement. Since then, I’ve filed over 100 issues (60% of which have been resolved), and committed over 140 changes, most of which seek to improve usability in the following ways, for example:

  • Packaging: making Docsy available as an NPM package, and eliminating the need for recursive git submodules. (Similar in spirit, another community member implemented Docsy support for Hugo modules.)
  • Customizability (styling), by removing hard-coded styles in Docsy layout files.
  • Google Analytics 4 (GA4) support

Most CNCF projects have similar needs for their websites, so upstreaming Docsy improvements benefits all Docsy-enabled CNCF projects, as well as the Docsy users at large. That’s the spirit of open source!

Steering Docsy’s evolution

In early 2022, I joined the Docsy Project Steering Committee (PSC). I welcomed the privilege to influence Docsy’s evolution: my primary goal has been on enhancing Docsy’s ease-of-use and customizability — examples of which were given above.

With this privilege also comes responsibilities, like reviewing community contributions, and rolling up our sleeves to coordinate and contribute to multi-person efforts for broadly-scoped changes such as upgrading Docsy to Bootstrap 5.

Contributors welcome!

The steering committee’s first order of business in 2023 will be upgrading Docsy to Bootstrap 5. Docsy is in feature freeze until this Bootstrap major-version upgrade is completed, because the currently used version of Bootstrap reached its end of life last fall. This upgrade will have an effect on almost every Docsy layout file, so contributors are most welcome for this multi-person effort, or any other Docsy issue!

Read More  Leading Towards More Trustworthy Compliance Through EU Codes Of Conduct

*4 GHz Intel i7 quad-core, 32 GB RAM

relay

Related Topics
  • Cloud Native Computing Foundation
  • Docsy
  • google
  • Open Source
You May Also Like
View Post
  • Engineering
  • Software Engineering

My First Pull Request At Age 14

  • March 24, 2023
View Post
  • DevOps
  • Engineering

Verify POST Endpoint Availability With Uptime Checks

  • March 24, 2023
View Post
  • Engineering
  • Tools

Monitor Kubernetes Cloud Costs With Open Source Tools

  • March 20, 2023
View Post
  • Engineering
  • People
  • Technology

Linux Foundation Training & Certification & Cloud Native Computing Foundation Partner With Corise To Prepare 50,000 Professionals For The Certified Kubernetes Administrator Exam

  • March 16, 2023
View Post
  • Engineering
  • People
  • Software Engineering

A Guide To Managing Your Agile Engineering Team

  • March 15, 2023
View Post
  • Engineering
  • People

10 Ways Wikimedia Does Developer Advocacy

  • March 15, 2023
View Post
  • Architecture
  • Computing
  • Design
  • Engineering
  • Multi-Cloud

3 Ways To Screw Up A Multicloud Deployment

  • March 14, 2023
View Post
  • Data
  • Engineering

Sentiment Analysis With BigQuery ML

  • March 13, 2023

Stay Connected!
LATEST
  • 1
    My First Pull Request At Age 14
    • March 24, 2023
  • 2
    AWS Chatbot Now Integrated Into Microsoft Teams
    • March 24, 2023
  • 3
    Verify POST Endpoint Availability With Uptime Checks
    • March 24, 2023
  • 4
    Sovereign Clouds Are Becoming A Big Deal Again
    • March 23, 2023
  • 5
    Ditching Google: The 3 Search Engines That Use AI To Give Results That Are Meaningful
    • March 23, 2023
  • 6
    Pythonic Techniques For Handling Sequences
    • March 21, 2023
  • 7
    Oracle Cloud Infrastructure to Increase the Reliability, Efficiency, and Simplicity of Large-Scale Kubernetes Environments at Reduced Costs
    • March 20, 2023
  • 8
    Monitor Kubernetes Cloud Costs With Open Source Tools
    • March 20, 2023
  • 9
    What Is An Edge-Native Application?
    • March 20, 2023
  • 10
    Eclipse Java Downloads Skyrocket
    • March 19, 2023
about
Hello World!

We are aster.cloud. We’re created by programmers for programmers.

Our site aims to provide guides, programming tips, reviews, and interesting materials for tech people and those who want to learn in general.

We would like to hear from you.

If you have any feedback, enquiries, or sponsorship request, kindly reach out to us at:

[email protected]
Most Popular
  • 1
    Cloudflare Takes On Online Fraud Detection Market
    • March 15, 2023
  • 2
    Linux Foundation Training & Certification & Cloud Native Computing Foundation Partner With Corise To Prepare 50,000 Professionals For The Certified Kubernetes Administrator Exam
    • March 16, 2023
  • 3
    Cloudflare Democratizes Post-Quantum Cryptography By Delivering It For Free, By Default
    • March 16, 2023
  • 4
    Daily QR “Scan Scams” Phishing Users On Their Mobile Devices
    • March 16, 2023
  • 5
    Lockheed Martin Launches Commercial Ground Control Software For Satellite Constellations
    • March 14, 2023
  • /
  • Platforms
  • Architecture
  • Engineering
  • Programming
  • Tools
  • About

Input your search keywords and press Enter.