fix: repair Home Manager option scraping for new mdBook docs #1

Merged

harald merged 1 commit from fix/home-manager-mdbook-scrape into main 2026-06-24 12:20:42 +02:00

Conversation 0 Commits 1 Files changed 6 +198 -8

harald commented 2026-06-24 12:20:32 +02:00

Owner

Copy link

Home Manager migrated its docs from a single DocBook options.xhtml
(definition lists) to an mdBook site. The old URL is now a ~1.4 KB
redirect stub with zero <dt> elements, so parse_html_options returned
an empty list and every Home Manager query (search/info/stats/browse)
silently reported "not found". That silence is the real hazard: callers
read it as "this option does not exist" and answer from stale knowledge
(e.g. recommending the long-removed programs.ssh.matchBlocks instead of
the current programs.ssh.settings DAG).

• Point HOME_MANAGER_URL at mdBook's combined print.html (every option
  on one page, ~5.5k anchors).
• Add parse_mdbook_options() for the <h2 id="opt-NAME"> + Type/Default/
  Example layout. It raises DocumentParseError when a page loads but has no
  option anchors, so a future structural break fails loudly instead of
  degrading to "not found".
• Surface Default and Example in info output (this is what carries the
  modern, correct option syntax).
• Route Home Manager search/info/stats/browse through the new parser;
  nix-darwin keeps the working DocBook <dt> parser.
• Add unit tests for the mdBook parser, including the loud-failure guard.

Home Manager migrated its docs from a single DocBook `options.xhtml` (definition lists) to an mdBook site. The old URL is now a ~1.4 KB redirect stub with zero `<dt>` elements, so `parse_html_options` returned an empty list and *every* Home Manager query (search/info/stats/browse) silently reported "not found". That silence is the real hazard: callers read it as "this option does not exist" and answer from stale knowledge (e.g. recommending the long-removed `programs.ssh.matchBlocks` instead of the current `programs.ssh.settings` DAG). - Point HOME_MANAGER_URL at mdBook's combined `print.html` (every option on one page, ~5.5k anchors). - Add `parse_mdbook_options()` for the `<h2 id="opt-NAME">` + Type/Default/ Example layout. It raises DocumentParseError when a page loads but has no option anchors, so a future structural break fails loudly instead of degrading to "not found". - Surface Default and Example in `info` output (this is what carries the modern, correct option syntax). - Route Home Manager search/info/stats/browse through the new parser; nix-darwin keeps the working DocBook `<dt>` parser. - Add unit tests for the mdBook parser, including the loud-failure guard.

harald added 1 commit 2026-06-24 12:20:32 +02:00

fix: repair Home Manager option scraping for new mdBook docs ... 49fb3a2110

Home Manager migrated its docs from a single DocBook `options.xhtml`
(definition lists) to an mdBook site. The old URL is now a ~1.4 KB
redirect stub with zero `<dt>` elements, so `parse_html_options` returned
an empty list and *every* Home Manager query (search/info/stats/browse)
silently reported "not found". That silence is the real hazard: callers
read it as "this option does not exist" and answer from stale knowledge
(e.g. recommending the long-removed `programs.ssh.matchBlocks` instead of
the current `programs.ssh.settings` DAG).

- Point HOME_MANAGER_URL at mdBook's combined `print.html` (every option
  on one page, ~5.5k anchors).
- Add `parse_mdbook_options()` for the `<h2 id="opt-NAME">` + Type/Default/
  Example layout. It raises DocumentParseError when a page loads but has no
  option anchors, so a future structural break fails loudly instead of
  degrading to "not found".
- Surface Default and Example in `info` output (this is what carries the
  modern, correct option syntax).
- Route Home Manager search/info/stats/browse through the new parser;
  nix-darwin keeps the working DocBook `<dt>` parser.
- Add unit tests for the mdBook parser, including the loud-failure guard.

harald merged commit db80bec9ec into main 2026-06-24 12:20:42 +02:00

harald referenced this pull request from a commit 2026-06-24 12:20:43 +02:00

Merge pull request 'fix: repair Home Manager option scraping for new mdBook docs' (#1) from fix/home-manager-mdbook-scrape into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

harald/mcp-nixos!1

No description provided.