How the cpp‑linter Team Built Their New Documentation Site with MkDocs‑Material

Introduction

After four years of maintaining cpp‑linter and creating many related projects and tools, the team realized that a simple description on the GitHub organization homepage was not user‑friendly. To better introduce the ecosystem, they built an official website, which went live at https://cpp-linter.github.io/ .

Home Page

The home page is intentionally simple, emphasizing entry points to the tools. It also displays a list of well‑known organizations and open‑source communities that use cpp‑linter, including Microsoft, Samsung, Apache, NASA, Stanford University, Cambridge University, and Lawrence Livermore National Laboratory.

Quick Start

A section explains how to quickly start using the cpp‑linter projects and tools.

Start Page

The start page lists all related projects and tools, providing brief introductions and links to each.

Discussion Page

The discussion area invites users to participate in conversations and share feedback.

Why This Approach?

Previous cpp‑linter documentation used GitHub Pages combined with MkDocs and the Material for MkDocs theme. To keep a consistent style, the new site also adopts the mkdocs‑material theme, and the team is satisfied with the final result.

Tips

If you want to build a website, start by finding a theme you like; a suitable theme better conveys your content. The team referenced design ideas, layout, and classification logic from excellent open‑source project sites such as astral.sh and the official mkdocs‑material site.

Conclusion

Successful open‑source projects need not only good code but also good documentation and a website to reach more users. The cpp‑linter ecosystem offers a one‑stop solution for C/C++ code formatting and static analysis. Contributions via issues or discussions are welcome, and readers are encouraged to share the site with fellow C/C++ developers.

References

[1] GitHub Pages: https://pages.github.com/

[2] MkDocs: https://www.mkdocs.org/

[3] Material for MkDocs: https://squidfunk.github.io/mkdocs-material/