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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
The same job on other stacks
- Show Last-Updated Dates on a Pelican Blog (Pelican)
- Add Last Updated Dates to Sphinx Docs (Sphinx)
- Add Last Updated Dates to a VitePress Blog (VitePress)