Trim browser-only chrome from ?output_format=md requests - #565
Open
jom wants to merge 1 commit into
Open
Conversation
…ests.
When a request asks for the markdown rendering (via ?output_format=md,
?output_format=markdown, or an Accept: text/markdown header) the
html-to-md mu-plugin converts the full template output to markdown.
Several pieces of that output are meaningful in the browser but pure
noise in the markdown body that consumers (LLMs, scripts) read:
- The "In this article" sidebar TOC and its "↑ Back to top" tail —
generated by wporg/sidebar-container + wporg/table-of-contents.
- The User Contributed Notes section (heading, login prompt / comment
form, list of notes, edit form) — wporg/code-reference-comment-form,
wporg/code-reference-comments, wporg/code-reference-user-notes,
wporg/code-reference-comment-edit.
- The handbook-page footer patterns: article-meta ("First published" /
"Last updated", duplicates the YAML frontmatter) and
handbook-pagination ("Previous:" / "Next:" nav links).
- The `author` YAML frontmatter field — on developer.wordpress.org it
rarely reflects authorship of the rendered content.
In addition, parameter `<dt>` markup like
`<code>$var</code><span class="type">…</span><span class="required">…</span>`
loses the visual gaps when converted to markdown (CSS does the
browser spacing). Insert plain whitespace between those spans on
markdown requests so the parameter line reads
`` `$var` string required `` instead of `` `$var`stringrequired ``.
Finally, the wporg/code-table block hides rows past `itemsToShow`
behind a JS "Show more" toggle that never runs in the markdown
context — bump the attribute to PHP_INT_MAX so the full Changelog /
Related tables render inline.
All changes are gated on a single is_markdown_request() check that
mirrors the html-to-md mu-plugin's detection, so the browser
rendering is unaffected.
jom
commented
May 18, 2026
| add_filter( 'pre_render_block', __NAMESPACE__ . '\\maybe_suppress_block', 10, 2 ); | ||
| add_filter( 'render_block_data', __NAMESPACE__ . '\\maybe_expand_code_table', 10 ); | ||
| add_filter( 'render_block_wporg/code-reference-parameters', __NAMESPACE__ . '\\maybe_space_param_dt', 10 ); | ||
| add_filter( 'html_to_markdown_frontmatter_fields', __NAMESPACE__ . '\\strip_author_field', 10 ); |
Author
There was a problem hiding this comment.
This is tied to dmsnell/html-to-md#16 and I'd consider it optional. Depending on timeline of merges, I'm happy to remove from this PR.
jom
commented
May 18, 2026
| 'wporg/sidebar-container', // Sidebar wrapper — also adds the "↑ Back to top" tail. | ||
| 'wporg/table-of-contents', // "In this article" sidebar TOC. | ||
| 'wporg/code-reference-comment-form', // Login prompt + comment form + heading. | ||
| 'wporg/code-reference-comments', // Rendered list of user notes. |
Author
There was a problem hiding this comment.
I was teetering on this change. Happy to revert if we think user comments are useful to the mostly-LLMs consuming them, but I thought it could be a good way to limit tokens.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
When a request asks for the markdown rendering (via
?output_format=md,?output_format=markdown, or anAccept: text/markdownheader), the html-to-md mu-plugin converts the full template output to markdown. Several pieces of that output are meaningful in the browser but pure noise in a markdown body intended for LLMs and scripted consumers.This PR adds a single
inc/markdown-output.phpwhose filters fire only whenis_markdown_request()is true, leaving the browser rendering untouched.What it suppresses on markdown requests
wporg/sidebar-container,wporg/table-of-contents)wporg/code-reference-comment-form,wporg/code-reference-comments,wporg/code-reference-user-notes,wporg/code-reference-comment-edit)article-meta("First published" / "Last updated" — already in the YAML frontmatter) andhandbook-pagination("Previous:" / "Next:" nav)authorYAML frontmatter field (rarely reflects authorship of the rendered content on this site)What it improves
wporg/code-tablerows pastitemsToShoware JS-hidden behind a "Show more" toggle; bumped toPHP_INT_MAXon markdown requests so the full Changelog / Related tables render inline<dt>markup is<code>$var</code><span class="type">…</span><span class="required">…</span>with CSS spacing — inject whitespace between the spans on markdown requests so the line reads`$var` string requiredinstead of`$var`stringrequiredMechanism
pre_render_blockshort-circuits suppressed blocks (andcore/patternby slug) — render callbacks and their queries never runrender_block_datamutateswporg/code-table'sitemsToShowattrrender_block_wporg/code-reference-parametersinjects parameter spacing into the rendered HTMLhtml_to_markdown_frontmatter_fieldsdrops theauthorkeyTest plan
?output_format=mdon a function page — confirm TOC, Back-to-top, and User Contributed Notes are gone; Changelog and Related render every row; parameters read with spaces?output_format=mdon a handbook page — confirm no "First published / Last updated" footer or Previous/Next navAccept: text/markdownheader without query arg behaves the same as?output_format=md