takaebato opened a new pull request, #100: URL: https://github.com/apache/echarts-www/pull/100
## Summary Follow-up to apache/echarts-doc#497, which added `llms.txt` and Markdown versions of the docs. This PR makes them discoverable from the doc pages themselves, for clients that fetch the raw HTML (AI coding agents in particular) and therefore only see the SPA shell. Two things are added, in `_jade/layouts/doc.jade` only (option, option-gl, api, tutorial, en and zh): - What the llms.txt proposal recommends: `<link rel="describedby" href="llms.txt">` in the head (https://llmstxt.org/). - What actually reaches the model in practice: a one-line hint with the full URL `https://echarts.apache.org/{lang}/llms.txt`, placed both inside a `<noscript>` block and as a plain `<p>` before `#ec-doc-main`. The fetch tools I tested keep different parts of the page, and none of them read the `<link>`: | Fetch tool | `noscript` text | Body text | `<link>` in head | | ----------------------------------------------- | --------------- | --------- | ---------------- | | Claude Code (HTML to Markdown, then summarized) | dropped | kept | dropped | | Codex (`web.run open`, main content extraction) | kept | dropped | dropped | With the hint present, an agent given only the page URL went straight to `llms.txt` and the relevant Markdown file instead of searching GitHub for the documentation source. Without it, none of the agents I tested tried `/llms.txt` on their own. The URL is written out in full because some tools (the Claude API web fetch tool ([ref](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-fetch-tool#url-validation)), for example) can only fetch URLs that already appear in the text they have seen. What each client sees: - Browser with JavaScript: nothing. The `<p>` is removed by an inline script (jQuery is already loaded on every page) before the SPA mounts, and `<noscript>` is not rendered. - Browser without JavaScript: the hint once, from `<noscript>`. A `<style>` inside the `<noscript>` block hides the `<p>`. - Fetch tool that keeps body text and drops `<noscript>` (Claude Code): the hint once, from the `<p>`. - Fetch tool that keeps `<noscript>` and drops boilerplate (Codex): the hint once, from `<noscript>`. The hint reuses the wording of the existing site-wide `noscript` message. ## Testing Built locally with `npm run sass` and `npm run jade`. The generated `en/option.html`, `zh/option.html`, and `en/api.html` contain the expected markup. In a browser, the hint is not shown with JavaScript enabled and is shown once with JavaScript disabled. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
