Skip to content

Trim browser-only chrome from ?output_format=md requests - #565

Open
jom wants to merge 1 commit into
WordPress:trunkfrom
jom:add/markdown-output-cleanup
Open

Trim browser-only chrome from ?output_format=md requests#565
jom wants to merge 1 commit into
WordPress:trunkfrom
jom:add/markdown-output-cleanup

Conversation

@jom

@jom jom commented May 18, 2026

Copy link
Copy Markdown

Summary

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 a markdown body intended for LLMs and scripted consumers.

This PR adds a single inc/markdown-output.php whose filters fire only when is_markdown_request() is true, leaving the browser rendering untouched.

What it suppresses on markdown requests

  • "In this article" sidebar TOC and its "↑ Back to top" tail (wporg/sidebar-container, wporg/table-of-contents)
  • User Contributed Notes — 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)
  • Handbook page footer patterns: article-meta ("First published" / "Last updated" — already in the YAML frontmatter) and handbook-pagination ("Previous:" / "Next:" nav)
  • The author YAML frontmatter field (rarely reflects authorship of the rendered content on this site)

What it improves

  • wporg/code-table rows past itemsToShow are JS-hidden behind a "Show more" toggle; bumped to PHP_INT_MAX on markdown requests so the full Changelog / Related tables render inline
  • Parameter <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 required instead of `$var`stringrequired

Mechanism

  • pre_render_block short-circuits suppressed blocks (and core/pattern by slug) — render callbacks and their queries never run
  • render_block_data mutates wporg/code-table's itemsToShow attr
  • render_block_wporg/code-reference-parameters injects parameter spacing into the rendered HTML
  • html_to_markdown_frontmatter_fields drops the author key

Test plan

  • Visit ?output_format=md on a function page — confirm TOC, Back-to-top, and User Contributed Notes are gone; Changelog and Related render every row; parameters read with spaces
  • Visit ?output_format=md on a handbook page — confirm no "First published / Last updated" footer or Previous/Next nav
  • Visit either page in a browser (no query arg) — confirm no visible change to the rendered page
  • Accept: text/markdown header without query arg behaves the same as ?output_format=md

…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.
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 );

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

'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.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant