feat(remark-includes): add plugin for external file inclusions#11271
Draft
batpigandme wants to merge 7 commits intostdlib-js:developfrom
Draft
feat(remark-includes): add plugin for external file inclusions#11271batpigandme wants to merge 7 commits intostdlib-js:developfrom
batpigandme wants to merge 7 commits intostdlib-js:developfrom
Conversation
Add a remark plugin to insert content from external Markdown files into a document using HTML comment directives. The plugin resolves include paths relative to the file being processed or a specified base directory, parses the external content into AST nodes, and replaces the content between opening and closing tags.
Assisted-by: Claude-Opus-4-6
---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
- task: lint_filenames
status: passed
- task: lint_editorconfig
status: passed
- task: lint_markdown
status: passed
- task: lint_package_json
status: passed
- task: lint_repl_help
status: na
- task: lint_javascript_src
status: passed
- task: lint_javascript_cli
status: na
- task: lint_javascript_examples
status: passed
- task: lint_javascript_tests
status: na
- task: lint_javascript_benchmarks
status: na
- task: lint_python
status: na
- task: lint_r
status: na
- task: lint_c_src
status: na
- task: lint_c_examples
status: na
- task: lint_c_benchmarks
status: na
- task: lint_c_tests_fixtures
status: na
- task: lint_shell
status: na
- task: lint_typescript_declarations
status: passed
- task: lint_typescript_tests
status: na
- task: lint_license_headers
status: passed
---
Add `markdown-includes` and `markdown-includes-files` rules to process Markdown files using the `remark-includes` plugin, enabling the automated insertion of content from external files.
---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
- task: lint_filenames
status: passed
- task: lint_editorconfig
status: passed
- task: lint_markdown
status: na
- task: lint_package_json
status: na
- task: lint_repl_help
status: na
- task: lint_javascript_src
status: na
- task: lint_javascript_cli
status: na
- task: lint_javascript_examples
status: na
- task: lint_javascript_tests
status: na
- task: lint_javascript_benchmarks
status: na
- task: lint_python
status: na
- task: lint_r
status: na
- task: lint_c_src
status: na
- task: lint_c_examples
status: na
- task: lint_c_benchmarks
status: na
- task: lint_c_tests_fixtures
status: na
- task: lint_shell
status: na
- task: lint_typescript_declarations
status: passed
- task: lint_typescript_tests
status: na
- task: lint_license_headers
status: passed
---
Add a check to verify that a base directory is available before attempting to resolve an include path and report an error if resolution is not possible. Assisted-by: Codex-GPT-5-4
Stores the current processor via this and parses include content with processor.parse, keeping parsing behavior aligned with the main remark pipeline. Assisted-by: GPT-5-4
Capture the remark processor context in the attacher via `this` and
pass it to the transformer factory, avoiding `consistent-this` and
`no-invalid-this` violations. Flip negated condition to satisfy
`no-negated-condition` and wrap long line for `max-len` compliance.
Assisted-by: Claude Opus 4.6 <noreply@anthropic.com>
---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
- task: lint_filenames
status: passed
- task: lint_editorconfig
status: passed
- task: lint_markdown
status: na
- task: lint_package_json
status: na
- task: lint_repl_help
status: na
- task: lint_javascript_src
status: passed
- task: lint_javascript_cli
status: na
- task: lint_javascript_examples
status: na
- task: lint_javascript_tests
status: na
- task: lint_javascript_benchmarks
status: na
- task: lint_python
status: na
- task: lint_r
status: na
- task: lint_c_src
status: na
- task: lint_c_examples
status: na
- task: lint_c_benchmarks
status: na
- task: lint_c_tests_fixtures
status: na
- task: lint_shell
status: na
- task: lint_typescript_declarations
status: passed
- task: lint_typescript_tests
status: na
- task: lint_license_headers
status: passed
---
---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
- task: lint_filenames
status: passed
- task: lint_editorconfig
status: passed
- task: lint_markdown
status: passed
- task: lint_package_json
status: na
- task: lint_repl_help
status: na
- task: lint_javascript_src
status: na
- task: lint_javascript_cli
status: na
- task: lint_javascript_examples
status: na
- task: lint_javascript_tests
status: na
- task: lint_javascript_benchmarks
status: na
- task: lint_python
status: na
- task: lint_r
status: na
- task: lint_c_src
status: na
- task: lint_c_examples
status: na
- task: lint_c_benchmarks
status: na
- task: lint_c_tests_fixtures
status: na
- task: lint_shell
status: na
- task: lint_typescript_declarations
status: passed
- task: lint_typescript_tests
status: na
- task: lint_license_headers
status: passed
---
Update the README to clarify how include paths are resolved when processing in-memory strings, consolidate usage examples, and document directive requirements and error handling behavior.
Assisted-by: GPT-5-3
---
type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes.
report:
- task: lint_filenames
status: passed
- task: lint_editorconfig
status: passed
- task: lint_markdown
status: passed
- task: lint_package_json
status: na
- task: lint_repl_help
status: na
- task: lint_javascript_src
status: na
- task: lint_javascript_cli
status: na
- task: lint_javascript_examples
status: na
- task: lint_javascript_tests
status: na
- task: lint_javascript_benchmarks
status: na
- task: lint_python
status: na
- task: lint_r
status: na
- task: lint_c_src
status: na
- task: lint_c_examples
status: na
- task: lint_c_benchmarks
status: na
- task: lint_c_tests_fixtures
status: na
- task: lint_shell
status: na
- task: lint_typescript_declarations
status: passed
- task: lint_typescript_tests
status: na
- task: lint_license_headers
status: passed
---
Member
Author
|
@kgryte, I've set this up so that the example use case we discussed wherein: # Hello World!
<!--<include path="./docs/snippets/foo.md"> -->
<!--</include> -->
<!-- <include path="./docs/snippets/bar.md"> -->
<!-- </include> -->
Would render to # Hello World!
<!--<include path="./docs/snippets/foo.md"> -->
## Greeting
Beep boop.
<!--</include> -->
<!--<include path="./docs/snippets/bar.md"> -->
## Bap
Bip bop.
<!--</include> -->
The fixture examples use My other two design questions are in the PR description (which I denoted with a little ❓ because humans can use emojis, too)! |
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.
Description
This pull request:
remark-includesplugin (@stdlib/_tools/remark/plugins/remark-includes) that resolves include directives in Markdown files, inserting content from external files between<!-- <include path="..."> -->and<!-- </include> -->comment tagstools/make/lib/markdown/includes.mk) withmarkdown-includesandmarkdown-includes-filestargets for running the plugin viamakeRelated Issues
No.
Questions
The plugin behavior (described below) currently defaults to resolving paths relative to the processed file's directory.
❓ If we plan to use this exclusively in
/docswould a different default be preferable?I realize that we don't use
thisin the repo and useselfinstead. In remark's unified API,thisin the attacher refers to the processor. So we capture it there (inattacher.js) and pass it to the factory.❓ Is there something I'm missing that would allow the use of
selfinstead ofthisconsistent with the codebase?Other
Plugin behavior
diroptionfile.message()) on missing files rather than haltingFuture work: consider adding
remark-includesto theto-htmlpipeline (@stdlib/_tools/markdown/to-html).Checklist
AI Assistance
If you answered "yes" above, how did you use AI assistance?
Disclosure
This PR was written primarily by Claude Code, with manual review and iteration on lint fixes, parser context handling, and base-path guards.
@stdlib-js/reviewers