Add minimal path format syntax reference to imports documentation #2097
Conversation
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
- Add comprehensive section on supported path formats - Document local relative paths, workflowspec format, section references - Document optional imports syntax and deprecated legacy syntax - Add practical examples for each format type - Include combined examples showing multiple formats together - Clarify behavior of path resolution and section extraction Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Copilot
AI
changed the title
[WIP] Update frontmatter imports documentation with supported formats
Update imports documentation with comprehensive path format reference
Oct 22, 2025
pelikhan
reviewed
Oct 22, 2025
Comment on lines
92
to
141
| **Requirements:** | ||
| - Must have at least 3 parts: `owner/repo/path` | ||
| - Cannot start with `.`, `shared/`, or `/` (these indicate local paths) | ||
| - File is downloaded from GitHub at compile time | ||
|
|
||
| ### 3. Section References | ||
|
|
||
| Import only a specific section from a markdown file: | ||
|
|
||
| ```yaml | ||
| imports: | ||
| - shared/guidelines.md#SecurityNotice | ||
| - githubnext/agentics/docs/best-practices.md@v1.0.0#Testing | ||
| ``` | ||
|
|
||
| **Behavior:** | ||
| - Extracts content from the specified header to the next same-level or higher-level header | ||
| - Supports H1 (`#`), H2 (`##`), and H3 (`###`) headers | ||
| - Section names are case-sensitive | ||
| - Works with both local and remote (workflowspec) paths | ||
|
|
||
| ### 4. Optional Imports | ||
|
|
||
| Mark imports as optional using the `?` modifier (supported in markdown directives only): | ||
|
|
||
| ```markdown | ||
| {{#import? shared/optional-config.md}} | ||
| {{#import? githubnext/agentics/experimental/beta-feature.md@develop}} | ||
| ``` | ||
|
|
||
| **Behavior:** | ||
| - If the file doesn't exist, a friendly informational message is shown | ||
| - Compilation continues without error | ||
| - Useful for environment-specific or conditional configurations | ||
|
|
||
| **Note:** Optional imports are only supported in markdown `{{#import?}}` directives, not in frontmatter `imports:` field. | ||
|
|
||
| ### 5. Deprecated Syntax (Legacy) | ||
|
|
||
| The following syntax is deprecated but still supported: | ||
|
|
||
| ```markdown | ||
| @include shared/file.md | ||
| @import shared/file.md | ||
| @include? shared/optional.md | ||
| ``` | ||
|
|
||
| **Migration:** Use `{{#import}}` instead: | ||
| - `@include path` → `{{#import path}}` | ||
| - `@include? path` → `{{#import? path}}` |
Contributor
Author
There was a problem hiding this comment.
Removed the deprecated syntax section in commit 365da41.
Remove the "Deprecated Syntax (Legacy)" section as requested by @pelikhan Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Replace verbose examples with minimal path format syntax reference as requested Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Contributor
Author
Copilot
AI
changed the title
Update imports documentation with comprehensive path format reference
Add minimal path format syntax reference to imports documentation
Oct 22, 2025
pelikhan
approved these changes
Oct 22, 2025
Contributor
|
Agentic Changeset Generator triggered by this pull request. |
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.
Overview
Updated the imports documentation (
/docs/src/content/docs/reference/imports.md) to add a concise syntax reference for all supported import path formats.Changes
Added Minimal Path Formats Section
The documentation now includes a concise "Path Formats" section with syntax reference for:
shared/,../), and absolute pathsowner/repo/path/file.md[@ref]#SectionName{{#import?}}for optional includesEach format is documented with minimal syntax examples showing the essential patterns without verbose explanations or detailed examples.
Testing
pkg/parser/frontmatter.goandpkg/workflow/imports.goRelated
Closes issue requesting documentation of all supported import path formats.
Original prompt
✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.