Add support for new import syntax {{#import}} and deprecate @include/@import by Copilot · Pull Request #1275 · github/gh-aw

Copilot · 2025-10-06T19:43:51Z

Overview

This PR implements the new {{#import ... }} syntax for imports in agentic workflows while maintaining full backward compatibility with the existing @include and @import syntax. The old syntax is now deprecated and will display helpful warnings during compilation.

Motivation

The new syntax provides better consistency with the existing {{#if ...}} template syntax and creates a clearer distinction between workflow directives and regular markdown content.

Changes

New Import Syntax

The following syntax is now available and recommended:

{{#import shared/tools.md}}           # Basic import
{{#import? shared/optional.md}}       # Optional import
{{#import shared/tools.md#Section}}   # Section-specific import

Note: While the colon after #import is supported internally for backward compatibility (e.g., {{#import: path}}), the recommended and documented syntax omits the colon for simplicity and consistency.

Deprecation Warnings

When using the old syntax, users now see clear migration guidance:

⚠ Deprecated syntax: '@include shared/tools.md'. Use '{{#import shared/tools.md}}' instead.
⚠ Deprecated syntax: '@include? shared/optional.md'. Use '{{#import? shared/optional.md}}' instead.
⚠ Deprecated syntax: '@import shared/config.md#Section'. Use '{{#import shared/config.md#Section}}' instead.

Implementation Details

Parser Updates: Enhanced regex pattern to support both old and new syntax simultaneously, with optional colon support (undocumented)
New Helper Function: Added ParseImportDirective() to classify and parse import directives
Deprecation Detection: Automatically identifies legacy syntax and emits warnings
Comprehensive Updates: Updated all import processing functions across the codebase
Documentation: Updated guides and examples to showcase the new recommended syntax (without colon)

Backward Compatibility

✅ All existing workflows continue to work without modification
✅ Old syntax (@include, @import) remains fully functional
✅ Colon syntax ({{#import: path}}) supported internally but not documented
✅ Deprecation warnings are informational and non-blocking
✅ No breaking changes
✅ Users can migrate at their own pace

Testing

Added comprehensive unit tests for new syntax parsing (with and without colon)
Added tests for deprecation warning behavior
Updated existing tests to match new error messages
All tests pass (unit and integration)
Manual testing confirms both syntaxes work correctly

Files Changed

pkg/parser/frontmatter.go - Core parser with dual syntax support and optional colon
pkg/parser/import_syntax_test.go - New comprehensive test suite
pkg/workflow/template.go - Validation updates
pkg/cli/imports.go & pkg/cli/remove_command.go - CLI processing updates
docs/src/content/docs/guides/packaging-imports.md - Documentation updates (simplified to show only syntax without colon)
.github/instructions/github-agentic-workflows.instructions.md - Agent instructions
.github/workflows/dev.md - Example workflow migrated to new syntax
Test files updated for new error messages

Migration Path

Users can adopt the new syntax gradually:

# Before (deprecated)
- @include shared/tools.md
- @include? shared/optional.md  
- @import shared/config.md#Section

# After (recommended)
+ {{#import shared/tools.md}}
+ {{#import? shared/optional.md}}
+ {{#import shared/config.md#Section}}

Fixes #1274

Original prompt

This section details on the original issue you should resolve

<issue_title>Syntax update</issue_title>
<issue_description>Use this syntax for imports in markdown:

{{#import: ... }}

Deprecated support for @include, @import: generate warning if found and suggest new syntax.</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #1274

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

…import Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

pelikhan

update to syntax to

The : is optinal and ignores

{{#import: ...}} # ok too, ignore :

pelikhan · 2025-10-06T20:12:17Z

@copilot update to syntax to

The : is optinal and ignores

{{#import: ...}} # ok too, ignore :

pelikhan · 2025-10-06T20:15:02Z

@copilot format, lint, recompile

…path}} Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot · 2025-10-06T20:23:22Z

@copilot update to syntax to

{{#import ...}}...

Done! The colon is now optional in the import syntax. Both {{#import path}} and {{#import: path}} work correctly. The documentation and examples have been updated to primarily show the syntax without the colon. (commit: short hash will be added after push)

@copilot update to syntax to

{{#import ...}}...

Done! The colon is now optional in the import syntax. Both {{#import path}} and {{#import: path}} work correctly. The documentation and examples have been updated to primarily show the syntax without the colon. (d895f46)

Copilot · 2025-10-06T20:28:42Z

@copilot format, lint, recompile

Done! ✓

Formatted: make fmt completed successfully
Linted: JavaScript formatting validated with prettier
Recompiled: All 59 workflow files compiled successfully with no changes

All unit tests pass. No commits needed as the code was already properly formatted and compiled.

pelikhan · 2025-10-06T20:30:33Z

+{{#import relative/path/to/file.md}}
+```
+
+Or with an optional colon:


do not document optional column @copilot

Removed optional colon documentation from Basic Import Syntax section.

pelikhan · 2025-10-06T20:31:03Z


 Imports files relative to the current markdown file's location.

 :::note


@copilot remove note

Removed the note about optional colon syntax.

pelikhan · 2025-10-06T20:31:26Z

+{{#import? relative/path/to/file.md}}
+```
+
+Or with a colon:


@copilot do not document colon syntax

Removed colon syntax documentation from Optional Imports and Section-Specific Imports sections.

pelikhan · 2025-10-06T20:31:55Z

+ {{#import shared/config.md#Section}}
+```
+
+You can also use the colon if preferred:


@copilot do not document colon

Removed the "You can also use the colon if preferred" section from Legacy Syntax.

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Initial plan

303c091

Copilot AI assigned Copilot and pelikhan Oct 6, 2025

Copilot started work on behalf of pelikhan October 6, 2025 19:44 View session

Copilot AI and others added 2 commits October 6, 2025 19:58

Add support for new import syntax {{#import:}} and deprecate @include/@…

d37f175

…import Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Update documentation and examples to use new import syntax

aebb35f

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

pelikhan reviewed Oct 6, 2025

View reviewed changes

Copilot AI changed the title ~~[WIP] Update import syntax handling for Markdown documentation~~ Add support for new import syntax {{#import:}} and deprecate @include/@import Oct 6, 2025

Copilot AI requested a review from pelikhan October 6, 2025 20:08

Copilot finished work on behalf of pelikhan October 6, 2025 20:08

Copilot started work on behalf of pelikhan October 6, 2025 20:12 View session

Make colon optional in import syntax: {{#import path}} or {{#import: …

d895f46

…path}} Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI changed the title ~~Add support for new import syntax {{#import:}} and deprecate @include/@import~~ Add support for new import syntax {{#import}} and deprecate @include/@import Oct 6, 2025

Copilot finished work on behalf of pelikhan October 6, 2025 20:25

Copilot started work on behalf of pelikhan October 6, 2025 20:25 View session

Copilot finished work on behalf of pelikhan October 6, 2025 20:29

pelikhan marked this pull request as ready for review October 6, 2025 20:30

pelikhan reviewed Oct 6, 2025

View reviewed changes

Copilot started work on behalf of pelikhan October 6, 2025 20:32 View session

Remove documentation about optional colon syntax

2bd4fa5

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>

Copilot AI requested a review from pelikhan October 6, 2025 20:36

Copilot finished work on behalf of pelikhan October 6, 2025 20:36

pelikhan merged commit e7fe454 into main Oct 6, 2025
27 checks passed

pelikhan deleted the copilot/update-import-syntax-handling branch October 6, 2025 20:45


		Imports files relative to the current markdown file's location.

		:::note

Conversation

Copilot AI commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Motivation

Changes

New Import Syntax

Deprecation Warnings

Implementation Details

Backward Compatibility

Testing

Files Changed

Migration Path

Comments on the Issue (you are @copilot in this section)

Uh oh!

pelikhan left a comment

Choose a reason for hiding this comment

Uh oh!

pelikhan commented Oct 6, 2025

Uh oh!

pelikhan commented Oct 6, 2025

Uh oh!

Copilot AI commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI commented Oct 6, 2025

Uh oh!

pelikhan Oct 6, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 6, 2025

Choose a reason for hiding this comment

Uh oh!

pelikhan Oct 6, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 6, 2025

Choose a reason for hiding this comment

Uh oh!

pelikhan Oct 6, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 6, 2025

Choose a reason for hiding this comment

Uh oh!

pelikhan Oct 6, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 6, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Copilot AI commented Oct 6, 2025 •

edited

Loading

Copilot AI commented Oct 6, 2025 •

edited

Loading