Conversation
Resolves #1266 Resolves #1267 Authors had no way to mark a block, a run of inline text, or a whole page as being in a different language or text direction, so the rendered HTML never got the lang/dir attributes needed for correct rendering (e.g. RTL scripts, screen readers, correct font/glyph shaping). The maintainers asked what concrete output this should produce. docutils/Sphinx were checked for prior art before designing this: - Document level: neither has any per-document mechanism at all (only project-wide build config), so nothing to align with there. - Inline level: docutils' own FAQ recommends exactly `:rtl:`/`:ltr:` roles for this, just via `.. role::` boilerplate the author has to write themselves; this makes them built-in instead. - Block level: docutils has `.. class:: language-<tag>` and `.. class:: rtl`/`ltr`, but that's CSS-only styling hooks with no real HTML lang/dir attribute, so it doesn't actually address the accessibility problem these issues are about. Kept our own `:lang:`/`:dir:` container options, which do emit real attributes. This reuses existing mechanisms at three levels rather than inventing new directives: - Block-level: `:lang:`/`:dir:` options on the existing `.. container::` / `.. div::` directive. - Inline-level: new `:rtl:`/`:ltr:` roles for pure direction switches, and a combined `:lang:` role (`` :lang:`text (language, direction)` ``) for text tagged with both, following the same trailing-`(...)` convention as the existing `:abbreviation:` role. - Document-level: new `:lang:`/`:dir:` field-list metadata, mirroring the existing `:template:` field, setting the page's own `<html>` tag. `dir` is validated against ltr/rtl/auto and `lang` against a loose BCP 47 shape; both are warn-only diagnostics, never blocking, matching the ValueType validation philosophy already used elsewhere. Signed-off-by: linawolf Assisted-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PP4LkejR5PSubbhNmF4RkT
jaapio
requested changes
Sep 17, 2026
jaapio
left a comment
jaapio
left a comment
Member
There was a problem hiding this comment.
I think direction should be an enum rather than an arbitrary string, this allows us to be more strict. We can validate the value before we create the enum, and otherwise fall back to auto when the value is invalid.
This will make sure rendering always works even if the userinput is wrong.
| #[Option(name: 'dir', description: 'Sets the HTML dir attribute on the wrapping div: "ltr", "rtl", or "auto".')] | ||
| final class ContainerDirective extends SubDirective | ||
| { | ||
| private const VALID_DIRECTIONS = ['ltr', 'rtl', 'auto']; |
Member
There was a problem hiding this comment.
Feels like this is a good candidate for an enum?
| final class LangTextRole extends BaseTextRole | ||
| { | ||
| private const VALID_DIRECTIONS = ['ltr', 'rtl', 'auto']; | ||
| private const LANGUAGE_TAG_PATTERN = '/^[a-zA-Z]{2,8}(-[a-zA-Z0-9]{1,8})*$/'; |
Member
There was a problem hiding this comment.
This seems to be repeated multiple times. Maybe we can use an interface with a constant to specify this? Something like Language
interface Language
const PATTERN =
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
2 participants
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.
Resolves #1266
Resolves #1267
Authors had no way to mark a block, a run of inline text, or a whole
page as being in a different language or text direction, so the
rendered HTML never got the lang/dir attributes needed for correct
rendering (e.g. RTL scripts, screen readers, correct font/glyph
shaping). The maintainers asked what concrete output this should
produce.
docutils/Sphinx were checked for prior art before designing this:
project-wide build config), so nothing to align with there.
:rtl:/:ltr:roles for this, just via
.. role::boilerplate the author has towrite themselves; this makes them built-in instead.
.. class:: language-<tag>and.. class:: rtl/ltr, but that's CSS-only styling hooks with noreal HTML lang/dir attribute, so it doesn't actually address the
accessibility problem these issues are about. Kept our own
:lang:/:dir:container options, which do emit real attributes.This reuses existing mechanisms at three levels rather than inventing
new directives:
:lang:/:dir:options on the existing.. container::/
.. div::directive.:rtl:/:ltr:roles for pure direction switches,and a combined
:lang:role (:lang:text (language, direction)) for text tagged with both, following the same trailing-(...)convention as the existing:abbreviation:` role.:lang:/:dir:field-list metadata, mirroringthe existing
:template:field, setting the page's own<html>tag.diris validated against ltr/rtl/auto andlangagainst a looseBCP 47 shape; both are warn-only diagnostics, never blocking, matching
the ValueType validation philosophy already used elsewhere.
🤖 Generated with Claude Code
https://claude.ai/code/session_01PP4LkejR5PSubbhNmF4RkT