Closes #21635: Migrate from mkdocs to Zensical

[jeremystretch]

Closes: #21635

• Drop mkdocs from requirements.txt and add Zensical
• Replace mkdocs with Zensical in CI and pre-commit tasks
• Remove .info from the docs/ build directory (obsolete)
• Update the legacy ReadTheDocs configuration

[pheus]

Thanks for working on this! The migration looks really good overall.

I noticed a few items that I think would be worth addressing before this is merged:

Upgrade script

upgrade.sh still builds the local docs with mkdocs build.

Could we update that as well?

Layout

Could we also update the footer/layout snippet to reflect Zensical?

<div class="md-copyright">
  {% if config.copyright %}
    <div class="md-copyright__highlight">
      {{ config.copyright }}
    </div>
  {% endif %}
  {% if not config.extra.generator == false %}
    Made with
    <a href="https://zensical.org/" target="_blank" rel="noopener">
      Zensical
    </a>
  {% endif %}
</div>
{% if not config.extra.build_public %}
  <div class="md-copyright">
    ℹ️ Documentation is being served locally
  </div>
{% endif %}

CSS update for image background

I think the image background styling should also be updated for both light and dark themes:

[data-md-color-scheme="default"] .md-content img {
    background-color: hsla(0, 0%, 95%, 1);
}

[data-md-color-scheme="slate"] .md-content img {
    background-color: hsla(0, 0%, 25%, 1);
}

instead of:

.md-content img {
    background-color: rgba(255, 255, 255, 0.64);
}

[jeremystretch]

@pheus good catches, thanks. I've updated upgrade.sh and removed the custom HTML footer entirely as it's no longer necessary.

Regarding the style change, are there any specific instances that this fixes? Or is it just a recommended tweak in general?

[pheus]

Thanks again!

On the style change, I do think it would be worth including as part of this PR if possible.

I noticed it in docs/installation/index.md, where the current image background comes across as fairly high-contrast in dark mode now that the new theme is noticeably darker than the previous MkDocs styling. Using theme-specific background values helps the images blend in much more naturally in both light and dark mode.

So while I don’t see it as a blocker, it does feel like a migration-related visual tweak rather than unrelated cleanup, which is why I’d lean toward including it here. That said, I’d also be fine treating it as follow-up polish if you’d prefer to keep this PR scoped.

[jeremystretch]

Yep that makes sense. I ended up just removing our custom CSS as the transparent image works in both light and dark modes naturally.

[casperklein]

mkdocs appears to have been re-added to requirements.txt: https://github.com/netbox-community/netbox/blob/v4.6.0/requirements.txt#L26

Is this intentional?