From e405f9f6e83bde2ae3e0049ae44d34fd97b0d0ba Mon Sep 17 00:00:00 2001 From: Aaron Date: Wed, 29 Apr 2026 00:31:51 +0800 Subject: [PATCH 1/3] updated docs --- docs/plugins/date-author.md | 48 +++++++++++++++++++---------- docs/plugins/offline.md | 2 +- docs/plugins/optimize.md | 2 +- docs/plugins/search.md | 2 +- docs/publishing-your-site.md | 2 +- docs/reference/tooltips.md | 2 +- docs/setup/setting-up-navigation.md | 2 +- mkdocs.yml | 1 + 8 files changed, 39 insertions(+), 22 deletions(-) diff --git a/docs/plugins/date-author.md b/docs/plugins/date-author.md index e45ac2a927..d36d3b1bb9 100644 --- a/docs/plugins/date-author.md +++ b/docs/plugins/date-author.md @@ -615,10 +615,15 @@ You can use this function to retrieve the date and author information for all si An example of calling the function is shown below: ``` py -from mkdocs_document_dates.utils import load_dates_and_authors from pathlib import Path from datetime import datetime +try: + from mkdocs_document_dates.utils import load_dates_and_authors +except ImportError: + load_dates_and_authors = None + + def __init__(self): super().__init__() self.date_data = {} @@ -626,23 +631,27 @@ def __init__(self): # First, call the API in `Global Events` to read data and store it def on_files(self, files, config): - ddPlugin = config.plugins.get("document-dates") - if ddPlugin: - self.date_data = ddPlugin.data_cached - else: - self.date_data = load_dates_and_authors(Path(config.docs_dir), files) + if load_dates_and_authors is not None: + # If the date plugin is enabled, load the data directly from the plugin; otherwise, get it from the API + dd_plugin = config.plugins.get("document-dates") + if dd_plugin: + self.date_data = dd_plugin.data_cached + else: + self.date_data = load_dates_and_authors(Path(config.docs_dir), files) + + # Continue with the original logic return files # Then, access the data via the relative path of page.file in `Page Events` def on_page_markdown(self, markdown, page: Page, config, files): - rel_path = getattr(page.file, 'src_uri') + entry = self.date_data.get(page.file.src_uri, {}) - created: datetime = self.date_data[rel_path]['created'] - updated: datetime = self.date_data[rel_path]['updated'] + created = entry.get("created") + updated = entry.get("updated") - authors = self.date_data[rel_path]['authors'] + authors = entry.get("authors", []) for author in authors: author.name author.email @@ -660,14 +669,21 @@ def on_page_markdown(self, markdown, page: Page, config, files): ``` py ... + def _parse_date(self, value: str | None, default: datetime | None) -> datetime | None: + if not value: + return default + try: + return datetime.fromisoformat(value).astimezone() + except ValueError: + return default + def on_page_markdown(self, markdown, page: Page, config, files): - created_str = page.meta.get('created') - if created_str: - created: datetime = datetime.fromisoformat(created_str).astimezone() - else: - rel_path = getattr(page.file, 'src_uri') - created: datetime = self.date_data[rel_path]['created'] + entry = self.date_data.get(page.file.src_uri, {}) + + # Overrides default values via meta fields + created = self._parse_date(page.meta.get("created"), entry.get("created")) + updated = self._parse_date(page.meta.get("updated"), entry.get("updated")) ... ``` diff --git a/docs/plugins/offline.md b/docs/plugins/offline.md index 243954d4c1..9e702d5048 100644 --- a/docs/plugins/offline.md +++ b/docs/plugins/offline.md @@ -1,6 +1,6 @@ --- title: Built-in offline plugin -icon: material/connection +icon: lucide/wifi-off --- diff --git a/docs/plugins/optimize.md b/docs/plugins/optimize.md index 31a8728c68..510ff27cca 100644 --- a/docs/plugins/optimize.md +++ b/docs/plugins/optimize.md @@ -1,6 +1,6 @@ --- title: Built-in optimize plugin -icon: material/rabbit +icon: material/bike-fast --- # Built-in optimize plugin diff --git a/docs/plugins/search.md b/docs/plugins/search.md index 28a82fe93a..920c3466a6 100644 --- a/docs/plugins/search.md +++ b/docs/plugins/search.md @@ -1,6 +1,6 @@ --- title: Built-in search plugin -icon: octicons/search-24 +icon: lucide/search --- # Built-in search plugin diff --git a/docs/publishing-your-site.md b/docs/publishing-your-site.md index c60ebf3823..9e72ddfff8 100644 --- a/docs/publishing-your-site.md +++ b/docs/publishing-your-site.md @@ -1,5 +1,5 @@ --- -icon: material/cloud-upload-outline +icon: lucide/cloud-upload --- # Publishing your site diff --git a/docs/reference/tooltips.md b/docs/reference/tooltips.md index 4661768568..04d35382a7 100644 --- a/docs/reference/tooltips.md +++ b/docs/reference/tooltips.md @@ -1,5 +1,5 @@ --- -icon: material/tooltip-plus-outline +icon: material/tooltip-text-outline --- # Tooltips diff --git a/docs/setup/setting-up-navigation.md b/docs/setup/setting-up-navigation.md index 3ba04f5655..c0b8a54f0e 100644 --- a/docs/setup/setting-up-navigation.md +++ b/docs/setup/setting-up-navigation.md @@ -1,5 +1,5 @@ --- -icon: material/navigation-variant-outline +icon: lucide/panel-left --- # Setting up navigation diff --git a/mkdocs.yml b/mkdocs.yml index cc96f7d8f5..ac640ac90d 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,6 +10,7 @@ site_description: >- repo_name: jaywhj/mkdocs-materialx repo_url: https://github.com/jaywhj/mkdocs-materialx +edit_uri: edit/main/docs/ copyright: Copyright © 2016 - 2026 Aaron Wang From e7cb414e01f4e1481b0406306e027fb90ca31fd9 Mon Sep 17 00:00:00 2001 From: Aaron Date: Thu, 30 Apr 2026 20:20:11 +0800 Subject: [PATCH 2/3] Add page support for markdown for AI agents (#61) --- material/templates/base.html | 8 ++++++++ mkdocs.yml | 1 + src/templates/base.html | 14 ++++++++++++++ 3 files changed, 23 insertions(+) diff --git a/material/templates/base.html b/material/templates/base.html index d65e139478..8c5750ca82 100644 --- a/material/templates/base.html +++ b/material/templates/base.html @@ -36,6 +36,14 @@ {% endif %} + {% if "content.action.agents" in config.theme.features and page.edit_url %} + {% if "/blob/" in page.edit_url %} + {% set part = "blob" %} + {% else %} + {% set part = "edit" %} + {% endif %} + + {% endif %} {% if config.theme.favicon %} {# 1. Try to capture the bundled icon if it exists #} {% set svg_raw %} diff --git a/mkdocs.yml b/mkdocs.yml index ac640ac90d..ede7c32562 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -39,6 +39,7 @@ theme: features: - content.action.edit - content.action.view + - content.action.agents - content.code.annotate - content.code.copy # - content.code.select diff --git a/src/templates/base.html b/src/templates/base.html index ff292c8046..0ff3d21324 100644 --- a/src/templates/base.html +++ b/src/templates/base.html @@ -87,6 +87,20 @@ /> {% endif %} + + {% if "content.action.agents" in config.theme.features and page.edit_url %} + {% if "/blob/" in page.edit_url %} + {% set part = "blob" %} + {% else %} + {% set part = "edit" %} + {% endif %} + + {% endif %} + {% if config.theme.favicon %} {# 1. Try to capture the bundled icon if it exists #} From 96c8dad654d37f7e65f0d91c135b24fd263ea5dd Mon Sep 17 00:00:00 2001 From: Aaron Date: Thu, 30 Apr 2026 21:58:50 +0800 Subject: [PATCH 3/3] updated docs --- docs/setup/adding-a-git-repository.md | 26 +++++++++++++++++++-- docs/setup/adding-document-dates-authors.md | 2 +- 2 files changed, 25 insertions(+), 3 deletions(-) diff --git a/docs/setup/adding-a-git-repository.md b/docs/setup/adding-a-git-repository.md index 256d6235a2..ada7ecfb44 100644 --- a/docs/setup/adding-a-git-repository.md +++ b/docs/setup/adding-a-git-repository.md @@ -39,7 +39,7 @@ automatically requested and rendered. sorted by update time], the [equivalent API endpoint] is used. So, make sure you also [create a release for GitLab repositories]. - [repo_url]: https://www.mkdocs.org/user-guide/configuration/#repo_url + [repo_url]: https://properdocs.org/user-guide/configuration/#repo_url [latest release]: https://docs.github.com/en/rest/reference/releases#get-the-latest-release [create a release]: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release [list of tags sorted by update time]: https://docs.gitlab.com/ee/api/tags.html#list-project-repository-tags @@ -160,7 +160,29 @@ theme: [GitLab]: https://about.gitlab.com/ [Bitbucket]: https://bitbucket.org/ [MkDocs]: https://www.mkdocs.org - [edit_uri]: https://www.mkdocs.org/user-guide/configuration/#edit_uri + [edit_uri]: https://properdocs.org/user-guide/configuration/#edit_uri + +#### Markdown for AI agents + + + + +Now, GEO (*SEO applied to AI agents*) is becoming an important stake for websites discoverability. +To allow AI agents (Claude Code, ChatGPT, etc.) to access pages more effectively, you can use the following configuration to let AI agents directly fetch the page Markdown source. + +This provides AI with well-structured content, **reduces token consumption by over 80%**, and greatly cuts down irrelevant noise. + +``` yaml +theme: + features: + - content.action.agents +``` + +!!! warning "Note" + - This feature relies on the [`repo_url`][repo_url]{target="_blank"} and [`edit_uri`][edit_uri]{target="_blank"} settings, you need to configure both properties correctly + - If the default branch of your GitHub repository is `main`, add the configuration: `edit_uri: edit/main/docs/` + +Related introduction: [Introducing Markdown for Agents](https://blog.cloudflare.com/zh-cn/markdown-for-agents/){target="_blank"} ### Document dates & authors diff --git a/docs/setup/adding-document-dates-authors.md b/docs/setup/adding-document-dates-authors.md index 9b1ccb96b5..0639963a11 100644 --- a/docs/setup/adding-document-dates-authors.md +++ b/docs/setup/adding-document-dates-authors.md @@ -167,7 +167,7 @@ show_author: text --- ``` -!!! tip "Note" +!!! warning "Note" When used in combination, the global toggle acts as the master switch, and the local toggle only takes effect when the master switch is enabled. This does not follow the logic of local configurations overriding global ones.