alleyinteractive / alleyinteractive/wp-block-converter
Handle Phrasing Content More Durably
- Dominant language
- PHP
- Stars
- 71
- Forks
- 5
- Avg merge
- 10d 6h
- Merged PRs (30d)
- 2
Description
### Description
Currently, we have a list of tags that constitute [phrasing content](https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Content_categories#phrasing_content), which is not exhaustive. That list of tags is used to determine when there is simple textual markup (e.g., bold, links) on what could otherwise be paragraph text. Following #90, we want to make this logic more robust so that we can reliably identify phrasing content in a way that makes sense for this library.
We can't use the MDN list as-is, because the MDN list of phrasing content includes elements that we want to convert to blocks (e.g., ``). We should investigate whether there is anything in the `\Dom\HTMLDocument` class or its family that allows us to use PHP to tell us whether an element is categorized as phrasing content or not, so we don't need to maintain that list ourselves. We do, however, need to maintain a list of tags that get converted to their own blocks, which we are already doing as methods (e.g., `p()` for paragraphs). Phrasing content should be defined as "categorized as phrasing content according to the spec, but not one of the elements that we are converting to a block, and does not recursively contain any elements we are converting to a block." For example, an anchor is phrasing content unless it wraps an image, at which point the anchor plus the image should be converted to a linked image block.
### Use Case
When someone uses this library and has markup in their source documents that is phrasing content that isn't part of the explicit list we have defined in this plugin, it won't convert as intended (see #89 for an example of this in practice). Also, as a maintainer, I should be able to rely on this list coming from specs and not needing to be hand-maintained as bugs come up.
Contributor guide
Research direction
Start by inspecting PHP’s \Dom\HTMLDocument class and its family, then trace the existing block-conversion methods such as p() and the phrasing-content list. Compare the available categorization behavior with the HTML specification and the exclusions described here. Done means phrasing content is detected without a hand-maintained general list, while block elements and nested cases such as an anchor containing an image still convert correctly.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php, wordpress
- Domain
- content
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100