Hexdoc

Added

* New block rendering system, implemented entirely in Python! This replaces [minecraft-render-py](https://github.com/hexdoc-dev/minecraft-render-py) and removes hexdoc's Node.js dependency. Block renders should now be much closer to how items look in inventories ingame.
* Note: Animated models currently only render the first frame of the animation.
* Note: `minecraft-render` is still included as a dependency for backwards compatibility reasons. This will be removed in a future release.
* New command: `hexdoc render-model`
* New dependencies: `frozendict`, `moderngl[headless]`, `moderngl-window`
* New `hexdoc.toml` field `lang.{lang}` for per-language configuration. Currently supported options include `quiet` and `ignore_errors`.

Changed

* Update `zh_cn` translations, by ChuijkYahus in [69](https://github.com/hexdoc-dev/hexdoc/pull/69).
* Blockstates are no longer taken into account when selecting block models to render.
* Deprecated the `--quiet-lang` CLI option.
* Errors will now always be raised for all languages unless explicitly disabled in `hexdoc.toml`. Previously, errors when rendering non-default languages would only fail the overall command in release mode.

Removed

* ⚠️ BREAKING: Removed `HexdocPythonResourceLoader`, as it was only needed for the old rendering system.
* ⚠️ BREAKING: Removed `HexdocAssetLoader.load_blockstates` and `HexdocAssetLoader.renderer_loader`. Several argument/return types have been changed from `IRenderClass` to `BlockRenderer`.
* Removed `hexdoc render-block` subcommands.

Added

* hexdoc now uses a custom `sys.excepthook` to hide unnecessary traceback frames, except in verbose mode.
* New reusable workflow input `site-url` to help support non-Pages deployments.

Changed

* Adding spoilers to individual pages with the `advancement` field is now supported.
* Use [`uv`](https://github.com/astral-sh/uv) instead of `pip` for all reusable workflows.
* `hexdoc ci build` now attempts to read the site url from `HEXDOC_SITE_URL` and `GITHUB_PAGES_URL` environment variables before querying the GitHub API.
* "No translation in {lang} for key {key}" warnings are now only printed once per key for each language to reduce log spam.

Added

* Web books will now generate a tree of redirects for categories, entries, and pages with anchors. These redirects include OpenGraph tags for generating Discord embeds.
* For example, https://hexcasting.hexxy.media/v/latest/main/1.19/en_us/basics now redirects to https://hexcasting.hexxy.media/v/latest/main/1.19/en_us#basics, and the Discord embed for the first link includes the category title "Getting Started".
* Added template variable `relative_site_url`, which is a relative path to the root of the website from the current page.
* For example, on the page `/v/latest/main/en_us`, `relative_site_url` would be `../../../..` .
* Added `HEXDOC_SUBDIRECTORY` environment variable and `subdirectory` GitHub Actions option, for deploying a hexdoc book alongside other sites/pages.
* Added the ability to print the installed hexdoc version with `hexdoc --version`.

Changed

* ⚠️ BREAKING: Replaced the `link_bases` system with `book_links` to simplify/improve the link system.
* This is what we use for constructing hrefs to internal and external categories/entries/pages. It's mostly only used internally, so this change hopefully won't have a big impact.
* Changed the Minecraft version in the dropdown to look like `Minecraft 1.19.2` instead of just `1.19.2`.
* Added more information to the hexdoc startup message, similar to what pytest prints.
* Updated minimum Pydantic version to `2.6.1`.
* Updated internal Pyright version from `1.1.343` to `1.1.345`.
* We have not updated to `1.1.346` or higher because that version and `1.1.350` both introduce some type errors related to the lack of a `TypeForm` type in Python. The new versions enforce that types like `Union` and `Annotated` should not count as `type`, which is something that Pydantic and hexdoc are currently doing.

Fixed

* [47](https://github.com/hexdoc-dev/hexdoc/issues/47): Concurrent builds overwrite each other because merge happens outside of the sequential part

Removed

* ⚠️ BREAKING: Removed `HexdocTypeAdapter` because `TypeAdapter` is now marked as final (and it never really worked properly anyway).

New Features

* Support for the rest of the default Patchouli page types, implemented by [SamsTheNerd](https://github.com/SamsTheNerd) in [#53](https://github.com/hexdoc-dev/hexdoc/pull/53)!
* Refactored recipe rendering for better reusability - see the default recipe page types for more details.
* Added `ModPlugin.default_rendered_templates_v2`, which works the same as `default_rendered_templates` but gets the book and context as arguments.
* This is meant to allow generating multi-file book structures instead of a single HTML document.
* `hexdoc.toml`: Added `template.render_from`, which is a list of modids to include default rendered templates from, defaulting to `template.include`.
* This can be used in conjunction with `template.include` to add a plugin's templates to the environment without rendering its default templates.

Changed

* The new version dropdown now only uses a submenu if there are at least 2 branches in a given version.
* Refactored `render` and `sitemap` out of `hexdoc.cli.utils` to more appropriate places.
* `ModPlugin.default_rendered_templates` (and `_v2`) may now return `tuple[str, dict[str, Any]]` as the dict value, where the string is the template to render and the dict contains extra arguments to pass to that template.

Removed

* Removed separators between versions in the new version dropdown to reduce visual clutter.

Fixed

* Overflowing text with long item names in the new dropdown submenus.
* Incorrect logic for deciding which dropdown items to disable (ie. the current book version being viewed).
* "Unhandled tag" error for page types without a namespace (Patchouli adds `patchouli:` if unspecified, but hexdoc didn't).

New Features

* Added `hexdoc_item`, a Jinja filter that looks up an `ItemWithTexture` from the item id.
* Syntax: `{{ texture_macros.render_item("minecraft:stone"|hexdoc_item) }}`
* Updated the version dropdown! Versions are now grouped by Minecraft version, and branches are hidden behind a submenu to reduce clutter.
* This allows you to use the same mod version for different Minecraft versions, as long as the plugin version is different.
* To switch back to the old style, add `hide_dropdown_minecraft_version = true` to the `[template.args]` section of your `hexdoc.toml` file.
* Added `BookPlugin`, a base class for implementing alternative book systems. This is still heavily WIP, and there **will** be more breaking changes. We're planning to use this to implement Modonomicon support.
* Internal: Added a Nox session to generate a dummy book for testing templates locally.

Changed

* ⚠️ BREAKING: Reworked book loading to support the new `BookPlugin` system. This *probably* won't affect most users, but it is a breaking change.
* `ModPlugin.jinja_template_root` may now return a list of template roots.
* `hexdoc_mod_plugin` may now return a list of plugins.
* `hexdoc merge` and `hexdoc ci merge` will now raise an error if trying to overwrite an existing version in release mode.
* If you need to bypass this, either pass `--no-release` to `hexdoc [ci] merge`, or delete the `.sitemap-marker.json` file(s) in the merge destination.
* The dropdown item for the current version is now disabled to give better feedback.
* Replaced our `JSONValue` type with an alias for Pydantic's `JsonValue` type.

Removed

* ⚠️ BREAKING: Removed reexports from `hexdoc.core` for `After_1_20`, `Before_1_19`, etc. They can still be imported from `hexdoc.core.compat` if needed, but this makes the namespace a bit cleaner.

Fixed

* `AttributeError` when generating error message for a nonexistent resource dir.
* Deserializing the union type `ItemWithTexture | TagWithTexture` sometimes returned `TagWithTexture` for non-tag inputs.

New Features

* Implemented Pydantic models for all remaining vanilla recipes (other than `minecraft:special_*`) and page types.
* Templates for the new page models are still WIP, but the models should now expose all necessary data.
* `hexdoc.toml`: Added support for directly specifying `patchouli_books` directories in `resource_dirs`.
* This is intended to support the [modpack book layout](https://vazkiimods.github.io/Patchouli/docs/patchouli-basics/getting-started#1-locate-patchouli_books), so the modid for this type of resource dir is always `patchouli`.
* Syntax:
toml
resource_dirs = [
{ patchouli_books="path/to/patchouli_books" },
]


Changed

* The `I18n` missing translation log level is now `DEBUG` when `book.i18n` is `False`.

Fixed

* Exception classname was not displayed in tagged union validation errors.