# Show Last Updated Dates on MkDocs Pages

Yes. An agent adds the git revision date plugin to your MkDocs site, keeps search working, gives CI the git history the plugin needs, and opens a pull request.

[Run this on Rush](https://cloud.getrush.ai/run/add-last-updated-dates/mkdocs/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads how the site is built and deployed before it adds a plugin, because this plugin reads git history, and a shallow checkout in CI gives it nothing to read. In a project laid out like encode/httpx, `mkdocs.yml` names the site, uses the `material` theme with a `custom_dir` of `docs/overrides` that holds one partial, `partials/nav.html`, sets `repo_url` and an empty `edit_uri`, and has a `nav` of five sections: Introduction and QuickStart, an Advanced section of ten pages from clients to extensions, Guides, an API Reference built from docstrings by the `mkautodoc` Markdown extension, and Community. There is no `plugins` key, which means MkDocs is running its default `search` plugin. `requirements.txt` pins the tooling, with a comment that says so, at `mkdocs` 1.6.1, `mkautodoc` 0.2.0 and `mkdocs-material` 9.6.18. `scripts/build` runs `python -m build`, `twine check` and `mkdocs build`; `scripts/publish` uploads to PyPI and runs `mkdocs gh-deploy --force`. `.github/workflows/test-suite.yml` runs `scripts/build` on every push and pull request across Python 3.9 to 3.13 after an `actions/checkout@v4` with no `fetch-depth`, and `publish.yml` runs the same checkout, build and publish on a tag. `docs/CNAME` names the public host.

The change to `mkdocs.yml` is a `plugins` list with two entries, and the first is the one people forget: declaring the list replaces the default, so `search` is written back explicitly ahead of `git-revision-date-localized`, as the plugin's own README says. The plugin's options are set in the open: `type: date`, `timezone: UTC` so a page shows the same date whoever builds it, `fallback_to_build_date: false` so a missing history fails the build rather than stamping today's date on every page, and `enable_creation_date` left off. Material renders the date at the bottom of each page when the plugin is enabled, so the `nav.html` override and the rest of the theme are untouched. `requirements.txt` gets `mkdocs-git-revision-date-localized-plugin` pinned like its neighbours.

CI needs one line in two places. Both workflows check out with the default depth of one commit, under which every file's last change looks like the checkout commit, and with the fallback off the plugin fails the build. The agent adds `fetch-depth: 0` to the `actions/checkout` step in `test-suite.yml` and `publish.yml`, so the build job and the deploy job see the full history and the dates on the published site are the real ones. The plugin's README names that setting for GitHub Actions, and the pull request says what it costs: the checkout fetches the whole repository instead of one commit.

The agent checks the result the way the site is built. It runs `scripts/build` in its sandbox on a full clone and reads the date in the rendered `site/quickstart/index.html`, then re-runs `mkdocs build` on a one-commit clone to show that the build now fails with the plugin's message rather than silently showing today's date, and pastes both into the pull request. It also calls out one thing the date cannot tell a reader: the API Reference pages are generated by `mkautodoc` from docstrings in the package, so their date is the last commit to the Markdown file that holds the `:::` directives, not the last change to the docstrings.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Show a last updated date on every page of this MkDocs site. Read mkdocs.yml, requirements.txt, scripts/build, scripts/publish, docs/overrides and every workflow under .github/workflows first. Add mkdocs-git-revision-date-localized-plugin to requirements.txt pinned like the other tooling. In mkdocs.yml add a plugins list that keeps search and adds git-revision-date-localized with type date, timezone UTC, fallback_to_build_date false and creation date off. Add fetch-depth: 0 to the actions/checkout step of every workflow that builds or deploys the docs, and say in the pull request why. Run the project's build script on a full clone and confirm the date appears in a rendered page, then run mkdocs build on a one-commit clone to show the build fails without history, and include both outputs. Note any pages whose content is generated from code so their date reflects the Markdown file and not the code. Do not change the theme overrides or the nav.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

The pull request changes `mkdocs.yml`, `requirements.txt`, `.github/workflows/test-suite.yml` and `.github/workflows/publish.yml`, and nothing else. Its description shows the rendered date line from one page after a full-clone build, the plugin's error from the one-commit build that explains why `fetch-depth: 0` is there, and the list of pages whose date tracks a Markdown file rather than the docstrings it pulls in.

`Test Suite` runs on the pull request with the deeper checkout, so the reviewer sees `scripts/build` pass with the plugin on a GitHub runner for every Python version in the matrix. `Publish` is unchanged apart from the checkout depth and still runs only on a tag, so the next release deploys pages with dates.

Before merging, a reviewer decides whether `timeago` reads better than a date for a site that changes often, whether a created date is worth a second line, and whether any page should be excluded from the date because it is edited by a script.

## Run it on every documentation site

An organisation with several MkDocs sites sends this body once per repository from its own server, each a `POST /o/{org}/sessions` with that repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own setup: a site that already declares `plugins` gets one entry appended, one that deploys from a `mkdocs gh-deploy` step in a different workflow gets the depth change there, one on GitLab gets `GIT_DEPTH` set instead, and one on the `readthedocs` theme gets the date added through a template block, since that theme does not render it on its own.

Once the date shows, the next event is a page that has not changed in a long time. An automation on the Project with a `schedule` trigger set to the first day of each month and the prompt "list the ten pages under docs/ with the oldest last commit, read each, and report which describe behaviour the code no longer has" turns the date into a review list rather than decoration. The automation's own `max_runs_per_hour` cap applies to it.

## Why run it on Rush?

The plugin is one line, and the three things around it are what go wrong: a `plugins` list that silently drops search, a CI checkout one commit deep that makes every page look edited today, and a fallback that hides exactly that. The agent reads the build and deploy scripts and both workflows first, writes the config with the fallback off, and runs the build in its own sandbox both with and without history so the pull request shows the failure the depth change prevents.

Both build outputs stay with the run and are pasted into the pull request, so the review is of a date the site rendered. Several sites get the same change at once, each with its own theme, deploy step and CI depth setting.

## Frequently asked questions

### Will search stop working?

No. MkDocs enables `search` by default only while no `plugins` key exists, so the agent writes `search` as the first entry of the new list before the date plugin. The pull request's build output includes the search index being written.

### Why change the workflows?

Because `actions/checkout` fetches one commit by default, and the plugin reads each file's last commit from git. With `fetch-depth: 0` the build and deploy jobs see the full history; without it, and with the fallback off, the build fails, which the pull request shows on purpose.

### Why not fall back to the build date?

Because a fallback would make a shallow checkout look like every page changed today, which is worse than no date. With `fallback_to_build_date` off, a missing history fails the build loudly, and the depth setting in CI is what makes it never happen.

### Does the date on the API reference reflect the code?

No. Those pages are built by `mkautodoc` from docstrings in the package, and the plugin dates the Markdown file that holds the directives. The pull request lists those pages so nobody reads an old date as a stale API.

## More MkDocs jobs

- [Add Link Checking to an MkDocs Site](https://getrush.ai/run/add-link-checking/mkdocs/)
- [Add llms.txt to a MkDocs Site](https://getrush.ai/run/add-llms-txt/mkdocs/)
- [Add Mermaid Diagrams to a MkDocs Site](https://getrush.ai/run/add-mermaid-diagrams/mkdocs/)

## The same job on other stacks

- [Show Last-Updated Dates on a Pelican Blog](https://getrush.ai/run/add-last-updated-dates/pelican/)
- [Add Last Updated Dates to Sphinx Docs](https://getrush.ai/run/add-last-updated-dates/sphinx/)
- [Add Last Updated Dates to a VitePress Blog](https://getrush.ai/run/add-last-updated-dates/vitepress/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
