MkDocs plugin to show the changes of documentation repositories in a user friendly format, at the same time that it's easy for the authors to maintain.
It creates daily, weekly, monthly and yearly newsletter articles with the
changes of each period. Those pages, stored under the
Newsletters section, are
filled with the changes extracted from the commit messages of the git history.
The changes are grouped by categories, subcategories and then by file using the
order of the site's navigation structure. RSS feeds are also
created for each newsletter type, so it's easy for people to keep updated with
the evolution of the site.
It assumes that you're using semantic versioning or our enhanced version to create your commits. Only those changes that are interesting to the reader will be added to the newsletter. You can use mkdocs-rss-plugin instead if this workflow doesn't feel good.
Check a live version.
This cool plugin creates two RSS feeds for the changes of the git history, one for new files and another for updated ones.
Creating an RSS entry for each change, it's not the ideal solution for digital gardens because:
- The user will receive too many updates: In a normal day, you can edit up to 10 files, which will create 10 RSS entries. That can annoy the user so it will stop reading your feed.
- The user will receive updates on irrelevant content: As an entry is created for each change, styling and grammar corrections are sent as a new full entry.
- The user receives no context of the change: The RSS entry links to the article but not it's sections, so if you frequently edit a big file, the, the user will see no point on the entry and skip it and in the end drop the RSS.
If you feel that your use case wont suffer from those conditions, I suggest you use their plugin instead, as it's much easier to use.
If there is enough people interested, we may develop:
- Support more notification channels such as email newsletters.
- Adding support for software repositories, to give updates on the releases.
As most open sourced programs,
mkdocs-newsletter is standing on the shoulders of
- Testing framework, enhanced by the awesome pytest-cases library that made the parametrization of the tests a lovely experience.
- Python static type checker.
- Python linter with lots of checks.
- Python formatter to keep a nice style without effort.
- Python formatter to automatically fix wrong import statements.
- Python formatter to order the import statements.
- Command line tool to manage the dependencies.
- To build this documentation site, with the Material theme.
- To check the installed dependencies for known security vulnerabilities.
- To finds common security issues in Python code.
- YAML fixer.
For guidance on setting up a development environment, and how to make a contribution to mkdocs-newsletter, see Contributing to mkdocs-newsletter.