Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docsy.dev/config/_default/hugo.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,9 @@ ignoreLogs:
- warning-frontmatter-params-overrides # cSpell:disable-line

outputs:
home: [HTML, Markdown]
page: [HTML, Markdown]
section: [HTML, RSS, print, Markdown]
home: [HTML, markdown]
page: [HTML, markdown]
section: [HTML, RSS, print, markdown]

imaging:
resampleFilter: CatmullRom # cSpell:disable-line
Expand Down
5 changes: 1 addition & 4 deletions hugo.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,7 @@ params:
rss_sections: [blog]

outputFormats:
Markdown:
isPlainText: true
mediaType: text/markdown
PRINT:
print:
baseName: index
# FIXME: leave isHTML unset (i.e. false) until we get a Hugo fix for
# https://github.com/gohugoio/hugo/issues/14381
Expand Down
36 changes: 18 additions & 18 deletions tasks/0.15/agent-friendly-support.plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ to the theme:
hand-tuned agent-facing output

The theme's job is to provide a reasonable default. The override path is
documented in Phase 3.
documented in Phase 4.

### Output format definition

Expand Down Expand Up @@ -141,22 +141,22 @@ Current goldens (covering the main template code paths):

## Rollout

- Phase 1: Markdown outputs via `all.md` (done in prototype)
- Phase 2: field-test on `docsy.dev` and external Docsy sites
- Phase 3: `llms.txt`
- Phase 4: docs
- Phase 1: Markdown outputs via `all.md` (complete; verified on `docsy.dev`)
- Phase 2: field-test on `docsy.dev` and external Docsy sites (in progress)
- Phase 3: `llms.txt` (not started)
- Phase 4: docs (not started)

### Phase 1: Markdown outputs (prototype complete)
### Phase 1: Markdown outputs (complete)

The `Markdown` output format is defined in `hugo.yaml`. The `layouts/all.md`
template is the default Markdown fallback used in this rollout. `docsy.dev`
enables the format via:

```yaml
outputs:
home: [HTML, Markdown]
page: [HTML, Markdown]
section: [HTML, RSS, print, Markdown]
home: [HTML, markdown]
page: [HTML, markdown]
section: [HTML, RSS, print, markdown]
```

The JS-driven `search.md` page explicitly opts out with `outputs: [HTML]`,
Expand All @@ -165,19 +165,19 @@ because an empty search shell adds little value for agents.
HTML output gains a `<link rel="alternate" type="text/markdown">` tag
automatically — this is Hugo's built-in behavior for alternate output formats.

### Phase 2: Field-testing
### Phase 2: Field-testing (in progress)

Validate the approach on real Docsy sites before investing in more complex
alternatives:

- Enable Markdown output on `docsy.dev` and review generated pages
- Field-test on an external Docsy site (e.g. OpenTelemetry) to evaluate whether
the `all.md` output is useful enough for agents in practice
- Gather feedback on which pages benefit most, which are too noisy, and whether
the progressive override path is sufficient
- Decide whether to invest in type-specific templates, Markdown-aware
shortcodes, or other refinements — or whether the simple approach is good
enough
- [x] Enable Markdown output on `docsy.dev` and review generated pages.
- [ ] Field-test on an external Docsy site (e.g. OpenTelemetry) to evaluate
whether the `all.md` output is useful enough for agents in practice.
- [ ] Gather feedback on which pages benefit most, which are too noisy, and
whether the progressive override path is sufficient.
- [ ] Decide whether to invest in type-specific templates, Markdown-aware
shortcodes, or other refinements — or whether the simple approach is good
enough.

### Phase 3: `llms.txt`

Expand Down
Loading