google / google/adk-docs

Document writing should consider the offline reading experience of Markdown.

Open
#659 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.