Skip to content

Document runtime markdown loading: when recompilation is required vs optional #12754

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
pelikhan merged 3 commits into from
Jan 30, 2026
Merged

Document runtime markdown loading: when recompilation is required vs optional #12754

pelikhan merged 3 commits into from
Jan 30, 2026

Conversation

Copy link
Contributor

Copilot AI commented Jan 30, 2026 •
edited
Loading

Plan: Update Documentation with Editing Tips

  • Understand the issue and codebase
    • Review how markdown body is loaded at runtime via {{#runtime-import}} macro
    • Review existing documentation structure
    • Identify best locations for new content
  • Add new guide document about editing workflows
    • Create a new guide explaining the difference between body and frontmatter
    • Explain when recompilation is needed vs not needed
    • Add practical examples and workflows
  • Update existing documentation references
    • Add to workflow structure documentation
    • Add to markdown reference documentation
    • Add to FAQ about editing on GitHub.com
    • Add to compilation process documentation
  • Build and validate documentation
    • Run make build-docs to ensure no errors
    • All links validated successfully
    • Documentation builds cleanly
  • Address PR feedback
    • Add reference to agentic authoring guide
    • Remove internal implementation details
    • Remove redundant sections (workflow, best practices, troubleshooting)
    • Simplify guide to focus on core concepts
Original prompt

Update the documentation with tips on editing the markdown body without recompilation (from GitHub web or editor) vs moshing the frontmatter and requiring compilation.

The markdown body is loaded at runtime and modification (aside from adding expressions using env. var.) do not require rexompilation so they can easily be done from dot com.

Custom agent used: technical-doc-writer
AI technical documentation writer for GitHub Actions library using GitHub Docs voice

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

@pelikhan
Add comprehensive guide on editing workflows with/without recompilation
68a5a9b 
- Created new guide: guides/editing-workflows.md
- Explains when markdown body can be edited without recompilation
- Explains when frontmatter changes require recompilation
- Added practical examples and quick reference table
- Updated workflow-structure.md to reference new guide
- Updated markdown.md with editing tips
- Added FAQ entry about editing on GitHub.com
- Updated compilation-process.md with tip about runtime loading
- All documentation builds successfully with no errors

Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
Copilot AI changed the title [WIP] Update documentation on editing markdown body Document runtime markdown loading: when recompilation is required vs optional Jan 30, 2026
Copilot AI requested a review from pelikhan January 30, 2026 14:46
pelikhan
pelikhan reviewed Jan 30, 2026
View reviewed changes
docs/src/content/docs/guides/editing-workflows.md
order: 5
---

Agentic workflows consist of two distinct parts with different editing requirements: the **YAML frontmatter** (configuration) and the **markdown body** (AI instructions). Understanding when changes require recompilation helps you iterate quickly and efficiently.
Copy link
Contributor

@pelikhan pelikhan Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot add refence to agentic authoring of workflows

Copy link
Contributor Author

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added reference to Authoring Workflows with AI guide in commit 9fd290e.

Updated guide with agentic authoring reference

docs/src/content/docs/guides/editing-workflows.md Outdated
Workflow files (`.md`) are compiled into GitHub Actions workflow files (`.lock.yml`). The compilation process:

- **Embeds frontmatter** directly into the lock file (changes require recompilation)
- **References the markdown body** at runtime via `{{#runtime-import}}` macro (changes do NOT require recompilation)
Copy link
Contributor

@pelikhan pelikhan Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot don't mention internal impl details

Copy link
Contributor Author

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed {{#runtime-import}} macro reference and simplified to "loads the markdown body at runtime from the source file" in commit 9fd290e.

docs/src/content/docs/guides/editing-workflows.md Outdated
Comment on lines 112 to 132
### Recompilation Workflow

```bash
# 1. Clone repository locally
git clone https://github.com/your-org/your-repo.git
cd your-repo

# 2. Edit the frontmatter in .github/workflows/my-workflow.md
vim .github/workflows/my-workflow.md

# 3. Recompile the workflow
gh aw compile my-workflow

# 4. Review changes
git diff .github/workflows/my-workflow.lock.yml

# 5. Commit and push
git add .github/workflows/my-workflow.md .github/workflows/my-workflow.lock.yml
git commit -m "Update workflow configuration"
git push origin main
```
Copy link
Contributor

@pelikhan pelikhan Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot remove lines

Copy link
Contributor Author

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed the Recompilation Workflow section in commit 9fd290e.

docs/src/content/docs/guides/editing-workflows.md Outdated

Use `needs.activation.outputs.text` for sanitized user input instead.

## Best Practices
Copy link
Contributor

@pelikhan pelikhan Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot remove section

Copy link
Contributor Author

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed the Best Practices section in commit 9fd290e.

docs/src/content/docs/guides/editing-workflows.md Outdated
- Auditability: Changes to compiled workflows are visible in git history
- Reproducibility: Anyone can see the exact configuration

## Troubleshooting
Copy link
Contributor

@pelikhan pelikhan Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot remove section

Copy link
Contributor Author

Copilot AI Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed the Troubleshooting section in commit 9fd290e.

@pelikhan
Address PR feedback: simplify guide and add agentic authoring reference
9fd290e 
- Added reference to Authoring Workflows with AI guide
- Removed internal implementation details (runtime-import macro)
- Removed Recompilation Workflow section (redundant)
- Removed Best Practices section (covered elsewhere)
- Removed Troubleshooting section (belongs in troubleshooting docs)
- Documentation builds successfully

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

Copilot AI commented Jan 30, 2026

Just as a heads up, I was blocked by some firewall rules while working on your feedback. Expand below for details.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

  • telemetry.astro.build
    • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)
    • Triggering command: /opt/hostedtoolcache/node/24.13.0/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro dev (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

Copilot AI requested a review from pelikhan January 30, 2026 15:06
@pelikhan pelikhan marked this pull request as ready for review January 30, 2026 15:07
@pelikhan pelikhan merged commit dd27d46 into main Jan 30, 2026
1 check passed
@pelikhan pelikhan deleted the copilot/update-documentation-editing-tips branch January 30, 2026 15:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@pelikhan pelikhan Awaiting requested review from pelikhan

Assignees

@pelikhan pelikhan

Copilot code review Copilot

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@pelikhan