Document writing should consider the offline reading experience of Markdown.
- Dominant language
- Shell
- Stars
- 1.5k
- Forks
- 1.3k
- Avg merge
- 7d 1h
- Merged PRs (30d)
- 34
Description
**Describe the bug**
When I read the documents at https://github.com/google/adk-docs locally, I found that some links cannot be accessed normally when reading Markdown offline.
Specifically, it uses path references in the form of `/adk-docs/xxxxx`, which causes the Markdown hyperlinks to not find the file. This can also be found by running the local site (using the `mkdocs server` command) and checking the build log for the issue.
**To Reproduce**
1. Run `mkdocs server` in the root directory of the local adk-docs repository.
2. The terminal will output the following information, with the marked part being the content with Markdown citation issues.
```diff
➜ adk-docs git:(main) mkdocs serve
INFO - Building documentation...
INFO - Cleaning site directory
+ INFO - Doc file 'index.md' contains an absolute link '/adk-docs/agents/config/', it was left as is.
+ INFO - Doc file 'agents/config.md' contains an absolute link '/adk-docs/api-reference/agentconfig/', it was left as is.
+ INFO - Doc file 'agents/config.md' contains an absolute link '/adk-docs/get-started/installation/#python', it was left as is.
+ INFO - Doc file 'agents/config.md' contains an absolute link '/adk-docs/get-started/installation/#python', it was left as is.
+ INFO - Doc file 'agents/config.md' contains an absolute link '/adk-docs/api-reference/agentconfig/', it was left as is.
+ INFO - Doc file 'agents/config.md' contains an absolute link '/adk-docs/get-started/quickstart/#run-your-agent', it was left as
+ is.
+ INFO - Doc file 'agents/config.md' contains an absolute link '/adk-docs/api-reference/cli/', it was left as is.
+ INFO - Doc file 'agents/config.md' contains an absolute link '/adk-docs/deploy/cloud-run/', it was left as is.
+ INFO - Doc file 'agents/config.md' contains an absolute link '/adk-docs/deploy/agent-engine/', it was left as is.
+ INFO - Doc file 'agents/config.md' contains an absolute link '/adk-docs/deploy/cloud-run/', it was left as is.
+ INFO - Doc file 'agents/config.md' contains an absolute link '/adk-docs/deploy/agent-engine/', it was left as is.
+ INFO - Doc file 'agents/config.md' contains an absolute link '/adk-docs/api-reference/agentconfig/', it was left as is.
+ INFO - Doc file 'callbacks/index.md' contains an absolute link
+ '/adk-docs/safety/#callbacks-and-plugins-for-security-guardrails', it was left as is.
+ INFO - Doc file 'plugins/index.md' contains an absolute link '/adk-docs/safety/#callbacks-and-plugins-for-security-guardrails',
+ it was left as is.
+ INFO - Doc file 'plugins/index.md' contains an unrecognized relative link
+ '../evaluate/#1-adk-web-run-evaluations-via-the-web-ui', it was left as is. Did you mean
+ '../evaluate/index.md#1-adk-web-run-evaluations-via-the-web-ui'?
+ INFO - Doc file 'plugins/index.md' contains an unrecognized relative link '../callbacks/', it was left as is. Did you mean
+ '../callbacks/index.md'?
+ INFO - Doc file 'plugins/index.md' contains an unrecognized relative link
+ '../evaluate/#1-adk-web-run-evaluations-via-the-web-ui', it was left as is. Did you mean
+ '../evaluate/index.md#1-adk-web-run-evaluations-via-the-web-ui'?
+ INFO - Doc file 'plugins/index.md' contains an absolute link '/get-started/quickstart/#run-your-agent', it was left as is. Did
+ you mean '../get-started/quickstart.md#run-your-agent'?
+ INFO - Doc file 'plugins/index.md' contains an unrecognized relative link
+ '../callbacks/types-of-callbacks/#agent-lifecycle-callbacks', it was left as is. Did you mean
+ '../callbacks/types-of-callbacks.md#agent-lifecycle-callbacks'?
+ INFO - Doc file 'safety/index.md' contains an absolute link '/adk-docs/plugins/#tool-callbacks', it was left as is.
+ INFO - Doc file 'tools/function-tools.md' contains an absolute link '/adk-docs/tools/performance/', it was left as is.
+ INFO - Doc file 'tools/function-tools.md' contains an absolute link '/adk-docs/tools/performance/', it was left as is.
+ INFO - Doc file 'tools/performance.md' contains an absolute link '/adk-docs/tools/function-tools/', it was left as is.
Building prefix dict from the default dictionary ...
Loading model from cache /var/folders/sq/4pvg07156sd37pvxbmnggmhw0000gn/T/jieba.cache
Loading model cost 1.394 seconds.
Prefix dict has been built successfully.
+ INFO - Doc file 'agents/config.md' contains a link '?tab=t.0#heading=h.xefmlyt7zh0i', but there is no such anchor on this page.
+ INFO - Doc file 'agents/multi-agents.md' contains a link '#12-workflow-agents-as-orchestrators', but there is no such anchor on
+ this page.
+ INFO - Doc file 'sessions/express-mode.md' contains a link 'session.md###sessionservice-implementations', but the doc
+ 'sessions/session.md' does not contain an anchor '###sessionservice-implementations'.
+ INFO - Doc file 'sessions/express-mode.md' contains a link 'memory.md###memoryservice-implementations', but the doc
+ 'sessions/memory.md' does not contain an anchor '###memoryservice-implementations'.
+ INFO - Doc file 'tools/index.md' contains a link '../tools/function-tools.md#1-function-tool', but the doc
+ 'tools/function-tools.md' does not contain an anchor '#1-function-tool'.
+ INFO - Doc file 'tools/index.md' contains a link '../tools/function-tools.md#3-agent-as-a-tool', but the doc
+ 'tools/function-tools.md' does not contain an anchor '#3-agent-as-a-tool'.
+ INFO - Doc file 'tools/index.md' contains a link '../tools/function-tools.md#2-long-running-function-tool', but the doc
+ 'tools/function-tools.md' does not contain an anchor '#2-long-running-function-tool'.
+ INFO - Doc file 'tools/mcp-tools.md' contains a link '../get-started/quickstart.md/#venv-install', but the doc
+ 'get-started/quickstart.md' does not contain an anchor '#venv-install'.
INFO - Documentation built in 17.59 seconds
INFO - [23:05:12] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO - [23:05:12] Serving on http://127.0.0.1:8000/adk-docs/
```
**Expected behavior**
The document is written with standard Markdown citation methods, considering the reading experience locally.
**Screenshots**
none.
**Versions**
- OS: Unrelated to this.
- ADK version: Unrelated to this.
- Python version: Unrelated to this.
**Additional context**
none.
Contributor guide
Assessment
This issue has not been assessed yet.