Usage¶

The recentupdate directive is the recommended way to display recent document updates. For cases where you need recent update information inside a sphinxnotes-render compatible template (e.g. alongside other extra contexts), use the recentupdate extra context instead.

The `recentupdate` Directive¶

.. recentupdate:: [count]¶

Display recent document updates from Git.

The optional count is the number of recent revisions to display. Defaults to recentupdate_count.

:self: (flag)¶

Only show revisions that modified the current document. Mutually exclusive with recentupdate:paths.

:paths: (lines of str)¶

List of git pathspecs (gitglossary(7)) to filter file changes, one per line. Default to . (Match current directory and its sub-directories).

Paths starting with / are relative to the Sphinx’s source directory (NOT the root of tit worktree); other paths are relative to the current document’s directory.

Note

Special marks in git pathspec like leading colon (:), attr mark (!, =, -) and so on are not supported for now.

The `recentupdate` Extra Context¶

Tip

The extra context is for use within sphinxnotes-render compatible templates. In most cases, prefer the recentupdate directive instead.

The recentupdate extra context can be loaded via load_extra in a Jinja template (e.g. via data.render):

Parameters:

count: Equivalent to the argument of recentupdate.
paths: Equivalent to recentupdate:paths.
self_only: Equivalent to recentupdate:self.
group_by: Equivalent to recentupdate:group-by.

This is a basic example:

Source

.. data.render::

   {% for r in load_extra('recentupdate', count=5) %}
   ``👤 {{ r.author }}`` @ ``📅 {{ r.date.strftime('%Y-%m-%d') }}``::

      {{ r.message[0] }}
   {% endfor %}

Result

👤 Shengyu Zhang @ 📅 2026-06-22:

chore: Bump version to 2.1

👤 Shengyu Zhang @ 📅 2026-06-22:

feat: Resolve paths relative to srcdir or current document

👤 Shengyu Zhang @ 📅 2026-06-22:

docs: Fix stray backtick in changelog

👤 Shengyu Zhang @ 📅 2026-06-21:

chore: Bump version to 2.0

👤 Shengyu Zhang @ 📅 2026-06-21:

docs: Improve recentupdate directive description in index.rst

Note

To Use the data.render directive, you need to add sphinxnotes.render.ext to your Sphinx extension list.

Examples¶

Show Which Documents Updated¶

Source

.. recentupdate::

   {% for r in revisions %}
   ``{{ r.date.strftime('%Y-%m-%d') }}``
      {% if r.changed_docs -%}
      :Modified: {{ r.changed_docs | roles("doc") | join(", ") }}
      {% endif %}
      {% if r.added_docs -%}
      :Added: {{ r.added_docs | roles("doc") | join(", ") }}
      {% endif %}
      {% if r.removed_docs -%}
      :Deleted: {{ r.removed_docs | join(", ") }}
      {% endif %}
   {% endfor %}

The aboved :external+render:term:`roles` filter is also provided by
`sphinxnotes-render`_.

Result

2026-06-22

Modified:: Change Log

2026-06-22

Modified:: sphinxnotes-recentupdate, Usage

2026-06-22

Modified:: Change Log

2026-06-21

Modified:: Change Log, sphinxnotes-recentupdate

2026-06-21

Modified:: sphinxnotes-recentupdate

The aboved roles filter is also provided by sphinxnotes-render.

Recent Updates of Custom Path¶

Source

Recent changes of the :doc:`changelog`

.. note:: The path is ``changelog.rst`` not ``docs/changelog.rst``

.. recentupdate::
   :paths: changelog.rst

   {% for r in revisions %}
   ``{{ r.date.strftime('%Y-%m-%d') }}`` — {{ r.message[0] }}
   {% endfor %}

Result

Recent changes of the Change Log

Note

The path is changelog.rst not docs/changelog.rst

2026-06-22 — chore: Bump version to 2.1

2026-06-22 — docs: Fix stray backtick in changelog

2026-06-21 — chore: Bump version to 2.0

2026-06-19 — refactor: Rename recentupdate_exclude_commit to recentupdate_skip_commit

2026-06-19 — feat: Add recentupdate directive using BaseContextDirective (#9)

Recent Updates to Current Document¶

Source

Recent changes to this document:

.. recentupdate::
   :self:

   {% for r in revisions %}
   ``{{ r.date.strftime('%Y-%m-%d') }}`` — {{ r.message[0] }}
   {% endfor %}

Result

Recent changes to this document:

2026-06-22 — feat: Resolve paths relative to srcdir or current document

2026-06-19 — feat: Add recentupdate directive using BaseContextDirective (#9)

2026-06-19 — docs: Format dates as YYYY-MM-DD in examples

2026-06-19 — docs: Restructure current_doc/paths mutual exclusion note

2026-06-18 — refactor: Move current_doc logic to generate() as pathspec conversion

Grouped Recent Updates¶

Source

Recent updates grouped by month:

.. recentupdate:: 3
   :group-by: month

   {% for r in revisions %}
   ``📅 {{ r.date.strftime('%Y-%m') }}``
      ::
         {% for msg in r.message[:20] %}
         {{ msg }}
         {%- endfor %}
         ...
   {% endfor %}

Result

Recent updates grouped by month:

📅 2026-06

feat: add path and current_doc parameters to recentupdate extracontext

- Add path parameter (str, default '.') for git pathspec filtering via iter_commits(paths=...)
- Add current_doc parameter (bool, default False) to only show revisions modifying the current document
- Rewrite _revisions() to use Repo.iter_commits(paths=...) instead of manual commit walking
- Handle root commit by traversing tree to find all added files
- Update generate() to use explicit keyword arguments instead of *args/**kwargs
- Fix deprecation: datetime.utcfromtimestamp() -> datetime.fromtimestamp(tz=timezone.utc)
- Add e2e tests with pre-constructed git repos (.gitdata pattern)

Co-authored-by: MiMoCode <mimo@xiaomi.com>
docs: Update usage

Co-authored-by: DeepSeek <service@deepseek.com>
refactor: Remove recentupdate_exclude_path config

The path parameter now provides equivalent functionality.

Co-authored-by: MiMoCode <mimo@xiaomi.com>
Merge pull request #6 from sphinx-notes/feat/path-and-current-doc-params
...

📅 2026-05

chore: Update project template to sphinx-notes/cookiecutter@233a8daa (#4)

Co-authored-by: OpenAI <noreply@openai.com>
refactor: Migrate to sphinxnotes-render (#5)

* refactor: Migrate to sphinxnotes-render for extra context and template rendering

- Replace custom directive and Jinja2 Environment with render's extra context
- Register @extra_context('recentupdates') accepting *args, **kwargs for count
- Register @filter('strftime') via render's filter system
- roles filter now provided by render, removing duplicate
- Drop recentupdate_count and recentupdate_template config values
- Remove RecentUpdateDirective and custom Environment class
- Update docs to show new load_extra('recentupdates', 10) usage

Co-authored-by: DeepSeek <service@deepseek.com>

* refactor: Rename extra context 'recentupdates' to 'recentupdate' for naming consistency

Co-authored-by: DeepSeek <service@deepseek.com>
...

📅 2025-10

chore: Bump version to 1.1
...

`sphinxnotes-render`¶

For more details about sphinxnotes-render:

Usage¶

The recentupdate Directive¶

The recentupdate Extra Context¶

Examples¶

sphinxnotes-render¶

The `recentupdate` Directive¶

The `recentupdate` Extra Context¶

`sphinxnotes-render`¶