layer5io / layer5io/docs

Add a hyperlink on every page for an LLM-friendly version of that page

Open
#1,205 13 comments 0 reactions 1 assignee Claimed by @sarbeshmallick View on GitHub
framework/hugo help wanted kind/enhancement language/css language/html language/javascript
Dominant language
JavaScript
Stars
99
Forks
223
Avg merge
1d 1h
Merged PRs (30d)
17

Description

### Current Behavior

Every page on docs.layer5.io renders only as styled HTML. There is no way for a reader (human or LLM/agent) to get a clean, LLM-friendly version of a page's content - e.g. raw Markdown, or plain text stripped of navigation, sidebars, footers, and other chrome. Anyone (or any tool) that wants to feed a page into an LLM today has to scrape and manually clean the rendered HTML, which is brittle and wastes context/tokens on non-content markup.

This is a increasingly common pattern on modern documentation sites (e.g. "Copy page", "View as Markdown", "Open in ChatGPT" links, and the emerging `llms.txt` convention) that make docs directly consumable by AI tools and agent workflows.

### Desired Behavior

Every page should expose a hyperlink (e.g. near the page title or in a page-actions menu) that links to, or produces, an LLM-friendly version of that page - clean Markdown or plain text with navigation chrome, styling, and site scaffolding stripped out, keeping only the substantive page content (headings, body text, code blocks, tables, links).

**Sourcing requirement (must be satisfied in this order):**
1. **Investigate upstream first.** Before building anything custom, determine whether this capability already exists in either:
- **Hugo core** (e.g. built-in output formats such as Markdown/plain-text output formats, `.Plain`/`.PlainWords`, or any first-class "alternate representation" mechanism), or
- **The Docsy theme** (`github.com/google/docsy`, currently pinned at v0.14.3 in [go.mod](go.mod)) - check its layouts/partials, release notes, and open/closed issues and PRs for an existing or in-progress "LLM-friendly page" / "copy as Markdown" / `llms.txt` feature.

Document findings (with links to the relevant Hugo docs, Docsy source, issues, or PRs) directly in this issue or in the linked PR.
2. **Only if neither Hugo nor Docsy already provides this** (natively or via a documented, supported extension point we can adopt) should a new, site-specific capability be built in this repo (e.g. via a custom Hugo output format targeting Markdown, a custom partial/shortcode, or a build-time export step that publishes a `.md`/`.txt` sibling for every page and links to it).

Either way, the resulting capability must:
- Apply automatically to every content page (no per-page manual opt-in).
- Produce output that is genuinely clean for LLM consumption - no nav/sidebar/footer/ads, but preserving heading structure, code fences, and links.
- Be discoverable via a visible hyperlink on the page itself (not only via a hidden/undocumented URL convention).

### Implementation

- Research spike: check Hugo's built-in output formats (`outputFormats` in `hugo.toml`/`config.yaml`) for a Markdown/plain-text option, and audit the Docsy theme (layouts, partials, changelog) for any existing "LLM-friendly" or "copy as Markdown" feature or open proposal upstream.
- If a Hugo output-format approach is viable, add a custom `outputFormat` (e.g. `text/markdown` at `/index.md`) and surface a link to it from the page layout/partial.
- If theme-level changes are the right fix, evaluate contributing upstream to Docsy rather than diverging locally.
- Consider alignment with the emerging [`llms.txt`](https://llmstxt.org/) convention for site-wide discoverability in addition to the per-page link.

### Acceptance Tests

- [ ] This issue (or the linked PR) documents whether Hugo core and/or the Docsy theme already provide this capability, with supporting links/evidence.
- [ ] Every rendered content page includes a visible hyperlink to an LLM-friendly (Markdown or plain-text) version of that page.
- [ ] The LLM-friendly version excludes site navigation, sidebar, footer, and other non-content chrome, and preserves headings, code blocks, tables, and links.
- [ ] The capability is sourced from upstream Hugo/Docsy if available there; a net-new custom implementation is added only if it is not.
- [ ] Solution is documented in the repo's contributor docs (e.g. `CONTRIBUTING.md` or a design doc under `docs/`) so future page templates/authors keep it working.

### Mockups

N/A - open to a small icon/link (e.g. "View as Markdown") placed near the existing page-edit/feedback links in the page header or footer.

---

#### Contributor Guide and Resources
- 📚 [Instructions for contributing to documentation](https://github.com/layer5io/docs/blob/master/CONTRIBUTING.md)
- Layer5 documentation [site](https://docs.layer5.io) and [source](https://github.com/layer5io/docs/)
- 🎨 Wireframes and [designs for Layer5 site](https://www.figma.com/file/5ZwEkSJwUPitURD59YHMEN/Layer5-Designs) in Figma [(open invite)](https://www.figma.com/team_invite/redeem/GvB8SudhEOoq3JOvoLaoMs)
- 🙋🏾🙋🏼 Questions: [Layer5 Discussion Forum](https://discuss.layer5.io) and [Layer5 Community Slack](http://slack.layer5.io)

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.