Goodbye, GitHub Discussions¶

With the launch of Zensical, we're evolving how we work together with the community to ensure long-term sustainability and professional support, fostering meaningful collaboration.

The launch of Zensical two weeks ago marked a significant milestone, as it establishes a new foundation for our mission to build scalable Open Source systems for technical writing. Additionally, we're adopting a structured, transparent, and community-driven approach to guide the evolution of our projects – prioritizing what to build, and shaping Zensical's future together.

Our new approach distills a decade of experience maintaining Material for MkDocs, allowing us to professionalize and scale our efforts from a small team to a fully organized operation, while keeping the software free and open to everyone.

As Material for MkDocs has entered maintenance mode, our discussion board is now read-only.

In this article, we reflect on the challenges we've navigated, the lessons we've learned, as these experiences have shaped our approach to community management and support that we're building with Zensical.

You can subscribe to our newsletter to stay in the loop.

This is the fourth article in a series:

1. Transforming Material for MkDocs
2. Zensical – A modern static site generator built by the creators of Material for MkDocs
3. Material for MkDocs Insiders – Now free for everyone
4. Goodbye, GitHub Discussions
5. What MkDocs 2.0 means for your documentation projects

GitHub Issues¶

Engagement with an Open Source project can take many forms – reporting bugs, submitting feature requests, seeking help, sharing ideas, participating in discussions, and contributing code. Each type of interaction requires a distinct approach to management.

Historically, we relied on our GitHub issue tracker to handle bug reports and feature requests. However, a significant portion of user inquiries – questions, support requests, and guidance – also found their way into the issue tracker. Over time, this blurred the lines between development work and support, making it increasingly difficult to maintain focus on core development tasks.

This is not unique to our project; many Open Source maintainers face similar challenges due to diverse skill levels and varying expectations within their communities. Clearly, Open Source projects needed a better solution to separate user support from development work.

GitHub Discussions¶

In 2020, GitHub launched GitHub Discussions as a dedicated space for community interaction – a new channel to move support requests away from issue trackers. We immediately enabled discussions for Material for MkDocs, and redirected users to post questions and seek help.¹

Then, as our community continued to expand – and as the vast majority of participants were seeking help rather than offering it – we launched the Community Experts Program, giving those community members free access to Insiders for consistently providing high-quality assistance.

Structural challenges¶

Despite these measures, we faced serveral structural challenges:

1. Material for MkDocs? MkDocs? Same, same – All too often, we were perceived as the entry point for the entire ecosystem. As a result, many issues and discussions that actually belonged upstream – such as problems with Python Markdown, MkDocs plugins, or MkDocs itself – landed on our desk. This created additional triage work for redirecting issues.

2. Yet another inbox – Although the discussion board was separate from the issue tracker, we ended up handling the majority of questions, effectively turning the discussion board into yet another inbox for us. Because the board is tied to the repository, unanswered discussions could be perceived as the project being unmaintained, putting pressure on us to respond.

3. A notification for everything – GitHub's notification system contributed to this problem. Any interaction within an issue or a discussion subscribes you to the entire thread, resulting in notifications for every comment, including: +1 – taking 2 seconds to type and submit, delivering a notification to the inbox of all other participants.

4. GitHub Discussions is a chat – Many users began treating GitHub Discussions more like a chat platform than a structured knowledge base. This created notification fatigue, reinforcing a pattern in which the community implicitly relied on maintainers to handle support requests. Everybody got a message, so the assumption was that things were taken care of – right?

5. Bug reports on our discussion board – From time to time, our contribution guidelines were ignored, leading to spurious bug reports on our discussion board instead of our issue tracker – "search doesn't work" is not an actionable bug report. However, when users followed our bug reporting guidelines, we were able to fix most bugs within 24-48 hours.

Addressing these challenges¶

We actively addressed these challenges in various ways over time: by introducing carefully crafted issue templates on our issue tracker and creating detailed step-by-step guides on how to report bugs, request changes, and create pull requests effectively.

Despite these efforts, success was limited. The underlying problem was that GitHub Discussions, while a step in the right direction, was not designed to handle the scale and diversity of our community. It lacked the structure and features necessary to support a large, active user base seeking help, making it impossible to fully resolve the challenges we faced. We believe that this is not unique to our project, but rather a systemic issue with GitHub Discussions, and that many Open Source maintainers encounter similar difficulties.

The Community Experts Program helped reduce some of the support burden, but it could not fully address the structural limitations of using GitHub Discussions for user support.

Discussions now read-only¶

With Material for MkDocs in maintenance mode, our GitHub Discussion board is now read-only – it remains accessible but will no longer accept new discussions or comments. All existing answers stay in place, ensuring that users can still find solutions to previously solved problems.

What this means for you¶

For issues and questions related to the broader MkDocs ecosystem, we encourage users to ask for assistance on the issue trackers and discussion boards of the respective upstream projects:

MkDocs & Python Markdown

• MkDocs – Issues, Discussions
• Python Markdown – Issues
• Pymdown Extensions – Issues, Discussions

Popular MkDocs plugins

• Mike – Issues, Discussions
• Macros – Issues, Discussions
• Git Revision Date Localized – Issues
• Awesome Nav – Issues
• Static i18n – Issues
• MkDocs Literate Nav – Issues

For all other MkDocs plugins and Markdown extensions, please consult the MkDocs catalog, and reach out to the maintainers of the respective projects.

Join our Discord to become part of Zensical's growing community!

Looking ahead¶

This article concludes our four-part series reflecting on the journey of maintaining Material for MkDocs and how it has paved the way for Zensical – our next chapter.

Our new approach to community management and support is built directly on the lessons we've learned over the years. We are excited to begin this next chapter together with you and look forward to cultivating a vibrant, engaged, and sustainable community together.

You can subscribe to our newsletter to stay in the loop.