Skip to content

[FEATURE] Render reStructuredText and Markdown files in one project - #1448

Open
CybotTM wants to merge 1 commit into
phpDocumentor:mainfrom
CybotTM:feature/mixed-input-formats
Open

CybotTM wants to merge 1 commit into
phpDocumentor:mainfrom
CybotTM:feature/mixed-input-formats

Conversation

@CybotTM

@CybotTM CybotTM commented Nov 8, 2026 •

Copy link
Copy Markdown
Contributor

Merging this lets one project mix reStructuredText and Markdown files: with input-format="rst,md", each .rst file is parsed as reStructuredText and each .md file as Markdown, in one document tree. Projects with one input format render as before.

The use case is a reStructuredText manual that also publishes documents kept in Markdown for other tools, such as specifications next to the code.

Known limits
  • An include of a file in the other format is not covered.
  • guides-pages calls the new ParseDirectoryCommand::getInputFormats() and Files::getExtension() while allowing phpdocumentor/guides ^1.0 || ^2.0, as guides-cli did with setViolationFormat() in [FEATURE] Annotate problems in the documentation source in GitHub and GitLab #1434.
  • ParseDirectoryCommand::getInputFormat() returns "rst,md" in a mixed project; listeners that use it as one extension should switch to getInputFormats().
Testing

New fixture tests/Integration/tests/configuration/config-mixed-input-formats: an RST index with a Markdown page in its toctree, links in both directions, an image and an excluded AGENTS.md. Also rendered a TYPO3 manual through render-guides with these files in vendor/ (TYPO3-Documentation/render-guides#1587).

@CybotTM
CybotTM force-pushed the feature/mixed-input-formats branch from fb07c98 to 34b569f Compare November 8, 2026 19:52
CybotTM added a commit to CybotTM/render-guides that referenced this pull request Nov 8, 2026
phpDocumentor/guides#1448 lets input-format in guides.xml list several
formats, such as "rst,md". Three places here assume one format.

RunDecorator passes the entry file's format as --input-format, which
overrides guides.xml and left out every Markdown page of an Index.rst
manual. A configured list that contains the entry's format is now kept,
once guides can read lists.

The headline anchor check skips Markdown, and the entry file check names
the file. Both now take the format from the file the page was parsed
from instead of the project setting.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>
@CybotTM
CybotTM force-pushed the feature/mixed-input-formats branch from 34b569f to 0de7f2a Compare November 8, 2026 20:36
@CybotTM

CybotTM commented Nov 8, 2026

Copy link
Copy Markdown
Contributor Author

CI fails here before the tests start because phpDocumentor/.github@v0.9 cannot install inotify on PHP 8.1–8.3; #1449 fixes that and is green.

CybotTM added a commit to CybotTM/render-guides that referenced this pull request Nov 8, 2026
phpDocumentor/guides#1448 lets input-format in guides.xml list several
formats, such as "rst,md". Three places here assume one format.

RunDecorator passes the entry file's format as --input-format, which
overrides guides.xml and left out every Markdown page of an Index.rst
manual. A configured list that contains the entry's format is now kept,
once guides can read lists.

The headline anchor check skips Markdown, and the entry file check names
the file. Both now take the format from the file the page was parsed
from instead of the project setting.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>
@CybotTM
CybotTM force-pushed the feature/mixed-input-formats branch 2 times, most recently from 7654d73 to 8520e71 Compare November 8, 2026 20:50
@CybotTM
CybotTM marked this pull request as ready for review November 8, 2026 20:53
The input-format setting takes a comma-separated list. With "rst,md"
every .rst file is parsed as reStructuredText and every .md file as
Markdown, in one document tree. A single format behaves as before.

Two files that differ only in their extension stop the run with an
error naming both.

Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
@CybotTM
CybotTM marked this pull request as draft November 21, 2026 12:06
@CybotTM
CybotTM force-pushed the feature/mixed-input-formats branch from 8520e71 to da6a40f Compare November 21, 2026 12:06
CybotTM added a commit to CybotTM/render-guides that referenced this pull request Nov 21, 2026
phpDocumentor/guides#1448 lets input-format in guides.xml list several
formats, such as "rst,md". Three places here assume one format.

RunDecorator passes the entry file's format as --input-format, which
overrides guides.xml and left out every Markdown page of an Index.rst
manual. A configured list that contains the entry's format is now kept,
once guides can read lists.

The headline anchor check skips Markdown, and the entry file check names
the file. Both now take the format from the file the page was parsed
from instead of the project setting.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: Sebastian Mendel <github@sebastianmendel.de>
@CybotTM
CybotTM marked this pull request as ready for review November 21, 2026 12:55
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