{"id":1504,"library":"hatch-fancy-pypi-readme","title":"Hatch Fancy PyPI README","description":"Hatch Fancy PyPI README is a Hatch plugin that enables dynamic and enhanced README generation for your Python packages. It allows you to combine multiple files, use Jinja templating, and perform other transformations to create a rich PyPI README. The current version is 25.1.0, and it is actively maintained as part of the Hatch project, with frequent updates.","status":"active","version":"25.1.0","language":"en","source_language":"en","source_url":"https://github.com/ofek/hatch-fancy-pypi-readme","tags":["hatch","pypi","readme","build-system","templating","packaging"],"install":[{"cmd":"pip install hatch-fancy-pypi-readme hatch","lang":"bash","label":"Install"}],"dependencies":[],"imports":[],"quickstart":{"code":"# 1. Create a project directory, e.g., 'my_fancy_package'\n# 2. Inside 'my_fancy_package', create these files:\n\n# pyproject.toml\n# --------------------------------------------------\n# [build-system]\n# requires = [\"hatchling>=1.18.0\", \"hatch-fancy-pypi-readme==25.1.0\"]\n# build-backend = \"hatchling.build\"\n# \n# [project]\n# name = \"my-fancy-package\"\n# version = \"0.1.0\"\n# description = \"A package with a fancy README\"\n# authors = [{ name = \"Agent\", email = \"agent@example.com\" }]\n# readme = { file = \"README.md\", content-type = \"text/markdown\", checker = \"fancy\" }\n# \n# [tool.hatch.build.targets.sdist.hooks.fancy-pypi-readme]\n# files = [\"README.md\", \"CHANGELOG.md\"]\n# template = \"# {{ project.name }} - v{{ project.version }}\\n\\n\" \\\n#            \"## Main README\\n{{ files['README.md'] }}\\n\\n\" \\\n#            \"## Changelog\\n{{ files['CHANGELOG.md'] }}\"\n# --------------------------------------------------\n\n# README.md\n# --------------------------------------------------\n# This is the primary README content for my package.\n# It will be combined with other files by hatch-fancy-pypi-readme.\n# --------------------------------------------------\n\n# CHANGELOG.md\n# --------------------------------------------------\n# ### 0.1.0\n# - Initial release with fancy README generation.\n# - Added support for combining README and CHANGELOG.\n# --------------------------------------------------\n\n# 3. Navigate to the 'my_fancy_package' directory in your terminal.\n# 4. Run the build command:\n# hatch build\n\n# After building, you will find the generated sdist and wheel files\n# in the 'dist/' directory, with the README correctly templated.","lang":"python","description":"This quickstart demonstrates how to use `hatch-fancy-pypi-readme` to combine `README.md` and `CHANGELOG.md` into a single, templated PyPI README. First, ensure `hatch` is installed. Then, create the specified `pyproject.toml`, `README.md`, and `CHANGELOG.md` files within your project directory. Finally, run `hatch build` to generate your package distributions with the fancy README."},"warnings":[{"fix":"Migrate your `pyproject.toml` to use the `project.readme` table with `checker = \"fancy\"` and subsequent configuration under `[tool.hatch.build.targets.sdist.hooks.fancy-pypi-readme]`, as shown in the quickstart example.","message":"The configuration for `hatch-fancy-pypi-readme` underwent a breaking change in version `21.0.0`. Older configurations using `[tool.hatch.build.hooks.fancy-readme]` are no longer supported.","severity":"breaking","affected_versions":"<21.0.0"},{"fix":"Carefully review the official documentation and examples for correct `pyproject.toml` structure. Pay close attention to the `checker = \"fancy\"` setting and the nested `tool.hatch` sections.","message":"Improper `pyproject.toml` configuration, especially around the `project.readme` table and the `[tool.hatch.build.targets.sdist.hooks.fancy-pypi-readme]` section, is a common source of errors. Ensure syntax is correct and all required fields are present.","severity":"gotcha","affected_versions":"All"},{"fix":"Thoroughly test your Jinja templates with sample data. Ensure all files referenced in `files` or within the template actually exist at build time. Use simpler templates initially and progressively add complexity.","message":"Errors in Jinja templates (e.g., syntax errors, referencing non-existent variables) or listing non-existent files in the `files` configuration will cause the build process to fail. Debugging templating issues can sometimes be challenging.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}