Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Switch to another static site generator (like Zensical)

Aperta
  • Qualcosa non va?
#132 1 commento 2 reazioni 1 assegnatario Vedi su GitHub

@peterjamesnugent ci sta già lavorando.

Dal 13/8/2026.

Valutazione

Questa issue non è ancora stata valutata.

Descrizione

severity:critical
TL;DR: I recommend we switch to Zensical, which should be a quick action for us to do, as it's authored by the same authors as of our Material for MkDocs website and made fully compatible and portable with it, ideally by November 6, 2026.

@al-fisher @peterjamesnugent

What happened

The creators of Material for MkDocs, which we rely upon for the BHoM Documentation, have been forced to take into account the changes being forced by the underlying system, MkDocs. MkDocs is being rewritten (version 2.0) and made incompatible with version 1.x, which our Material for MkDocs BHoM documentation site uses.

MkDocs 2.0 was announced – a ground-up rewrite of the documentation tool tens of thousands of projects rely on, introducing potentially significant breaking changes.
...
MkDocs 1.x is unmaintained, with issues and PRs piling up and no releases in the past 18 months, and seemingly no plans to fix long-standing issues like live-reload problems. More importantly, it's unclear whether security issues will be addressed, and whether the project will receive any updates at all in the future.

Therefore, the authors have set Material for MkDocs in maintenance mode until November 6, 2026, allowing users to migrate to another solution:

Material for MkDocs is in maintenance mode

We want to be transparent about the risks of staying on Material for MkDocs or on forks of both Material for MkDocs and MkDocs. With MkDocs 1.x unmaintained and facing fundamental supply chain concerns, its future is uncertain and we cannot guarantee Material for MkDocs will continue working reliably. MkDocs 2.0 will introduce breaking changes – something we analyzed thoroughly in our MkDocs 2.0 article.

We're aware that transitioning takes time, which is why we commit to supporting Material for MkDocs for at least the next 12 months, fixing critical bugs and security vulnerabilities as needed. If you have questions about your specific situation or need help planning a migration, don't hesitate to reach out at [email protected].

The authors of Material for MkDocs have authored a replacement solution, Zensical, which is designed to be a drop-in replacement to both Material for MkDocs and MkDocs itself:

Zensical is designed to be a drop-in replacement for MkDocs 1.x, with the goal of building your existing projects without any changes.
...
To make the transition seamless, compatibility comes first. We're putting significant effort into ensuring a smooth migration from Material for MkDocs for all users. Zensical can natively read mkdocs.yml, allowing you to build your existing project with minimal changes. As of now, a subset of plugins is supported, and we're working on feature parity in the coming months.

Zensical is fully Open Source, licensed under MIT, and can be used for any purpose, including for commercial use.
...
Rather than turning this into a marketing pitch, we encourage you to read the announcement post if you'd like to understand how Zensical differs from MkDocs and what you can already expect today. Additionally, the compatibility section on our website offers an overview of what features are already supported without changes.

Lingua principale
C#
Stelle
88
Fork
18
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di BHoM/documentation

Tutte le issue di BHoM/documentation

Issue simili

Altre issue su C#

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.