{"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":"python","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,"search_vec":"'25.1.0':48 'activ':52 'allow':25 'build':67 'build-system':66 'combin':28 'creat':39 'current':45 'dynam':15 'enabl':14 'enhanc':17 'fanci':2,6 'file':30 'frequent':61 'generat':19 'hatch':1,5,11,58,63 'jinja':32 'maintain':53 'multipl':29 'packag':23,70 'part':55 'perform':35 'plugin':12 'project':59 'pypi':3,7,42,64 'python':22 'readm':4,8,18,43,65 'rich':41 'system':68 'templat':33,69 'transform':37 'updat':62 'use':31 'version':46","created_at":"2026-04-09T03:50:47.006995+00:00","updated_at":"2026-04-16T15:32:33.441967+00:00","problems":[{"fix":"Ensure `hatch-fancy-pypi-readme` is installed in the same environment where the `hatch` CLI command resides. Verify your `pyproject.toml` has a `[tool.hatch.metadata.hooks.fancy-pypi-readme]` section and that the main `[project]` table does *not* contain a `readme` key that conflicts with the plugin's configuration.","cause":"This error occurs when Hatch cannot find or load the 'fancy-pypi-readme' plugin, often due to it not being installed in the Hatch environment or a misconfiguration in `pyproject.toml`.","error":"unknown metadata hook"},{"fix":"Review the paths specified for your fragments in `pyproject.toml`. Ensure they are correct relative to your project root. In CI/CD, confirm that the action or workflow is running from the expected working directory, or adjust paths to be absolute if necessary.","cause":"This error indicates that the plugin, during the README generation process, is unable to locate the files specified in the `fragments` section of your `pyproject.toml` configuration, often due to incorrect relative paths or issues with the working directory, especially in CI/CD environments like GitHub Actions.","error":"hatch-fancy-pypi-readme cannot find fragment files"},{"fix":"Install `hatch-fancy-pypi-readme` using pip in the same virtual environment where Hatch is installed: `pip install hatch-fancy-pypi-readme`.","cause":"This error means the Python interpreter cannot find the `hatch_fancy_pypi_readme` package when Hatch attempts to load it, most commonly because the plugin has not been installed, or it's installed in a different Python environment than Hatch.","error":"ModuleNotFoundError: No module named 'hatch_fancy_pypi_readme'"},{"fix":"Set the `content-type` in your `pyproject.toml` to either `'text/markdown'` or `'text/x-rst'`, as these are the only formats currently supported by PyPI. For example: `content-type = \"text/markdown\"`.","cause":"This validation error occurs when the `content-type` specified in the `[tool.hatch.metadata.hooks.fancy-pypi-readme]` section of `pyproject.toml` is not one of the allowed values.","error":"Error: `content-type` must be either 'text/markdown' or 'text/x-rst'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"hatch","cli_version":"Hatch, version 1.16.5","type":"library","homepage":null,"github":"https://github.com/hynek/hatch-fancy-pypi-readme","docs":"https://github.com/hynek/hatch-fancy-pypi-readme#readme","changelog":"https://github.com/hynek/hatch-fancy-pypi-readme/blob/main/CHANGELOG.md","pypi":"https://pypi.org/project/hatch-fancy-pypi-readme/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-04-09","next_check":"2026-07-08","install_tag":null}}