Skip to content

Commit 39f7263

Browse files
rvbenrvben
committed
feat(flavor): add GitHub Agentic Workflows preview support
1 parent 4b54ce5 commit 39f7263

40 files changed

Lines changed: 1048 additions & 104 deletions

‎.rumdl.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,3 +57,4 @@ style = "aligned"
5757
# Per-file flavor configuration
5858
[per-file-flavor]
5959
"docs/**/*.md" = "mkdocs"
60+
"tests/fixtures/gh_aw/*.md" = "gh-aw"

‎CHANGELOG.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
### Added
11+
12+
- **flavor**: add preview support for GitHub Agentic Workflows (`gh-aw`), including imports and current conditional branch syntax
13+
- **Rust API**: add `MarkdownFlavor::GhAw`; downstream exhaustive matches must handle the new variant
14+
15+
### Fixed
16+
17+
- **MD057**: exclude Markdown-looking frontmatter strings from body link validation and workspace indexing
18+
- **MD041**: never move or promote headings across GitHub Agentic Workflow control boundaries
19+
1020
## [0.2.63](https://github.com/rvben/rumdl/compare/v0.2.62...v0.2.63) - 2026-09-02
1121

1222
### Added

‎README.md‎

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -615,20 +615,21 @@ rumdl supports multiple Markdown flavors to accommodate different documentation
615615

616616
### Supported Flavors
617617

618-
| Flavor | Use Case | Key Features |
619-
| -------------------------------------------- | ---------------------------- | --------------------------------------------------- |
620-
| [standard](docs/flavors/standard.md) | Default Markdown | CommonMark + GFM extensions (tables, task lists) |
621-
| [gfm](docs/flavors/gfm.md) | GitHub Flavored Markdown | Extended autolinks, security-sensitive HTML |
622-
| [mkdocs](docs/flavors/mkdocs.md) | MkDocs / Material for MkDocs | Admonitions, content tabs, mkdocstrings |
623-
| [mdx](docs/flavors/mdx.md) | MDX (JSX in Markdown) | JSX components, ESM imports, expressions |
624-
| [quarto](docs/flavors/quarto.md) | Quarto / RMarkdown | Citations, shortcodes, executable code blocks |
625-
| [pandoc](docs/flavors/pandoc.md) | Pandoc Markdown | Fenced divs, attribute lists, citations, math |
626-
| [obsidian](docs/flavors/obsidian.md) | Obsidian | Tag syntax (#tagname treated as tags, not headings) |
627-
| [kramdown](docs/flavors/kramdown.md) | Jekyll / kramdown | IALs, ALDs, extension blocks |
628-
| [azure_devops](docs/flavors/azure_devops.md) | Azure DevOps Wiki | Colon code fences (:::lang ... :::) |
629-
| [myst](docs/flavors/myst.md) | MyST / Jupyter Book / Sphinx | Directives, roles, `%` comments |
630-
| [hugo](docs/flavors/hugo.md) | Hugo / Goldmark | Block attribute lists |
631-
| [mdg](docs/flavors/mdg.md) | Markdown with Gherkin | Gherkin-safe headings, tags, Doc Strings, tables |
618+
| Flavor | Use Case | Key Features |
619+
| -------------------------------------------- | ---------------------------------- | --------------------------------------------------- |
620+
| [standard](docs/flavors/standard.md) | Default Markdown | CommonMark + GFM extensions (tables, task lists) |
621+
| [gfm](docs/flavors/gfm.md) | GitHub Flavored Markdown | Extended autolinks, security-sensitive HTML |
622+
| [mkdocs](docs/flavors/mkdocs.md) | MkDocs / Material for MkDocs | Admonitions, content tabs, mkdocstrings |
623+
| [mdx](docs/flavors/mdx.md) | MDX (JSX in Markdown) | JSX components, ESM imports, expressions |
624+
| [quarto](docs/flavors/quarto.md) | Quarto / RMarkdown | Citations, shortcodes, executable code blocks |
625+
| [pandoc](docs/flavors/pandoc.md) | Pandoc Markdown | Fenced divs, attribute lists, citations, math |
626+
| [obsidian](docs/flavors/obsidian.md) | Obsidian | Tag syntax (#tagname treated as tags, not headings) |
627+
| [kramdown](docs/flavors/kramdown.md) | Jekyll / kramdown | IALs, ALDs, extension blocks |
628+
| [azure_devops](docs/flavors/azure_devops.md) | Azure DevOps Wiki | Colon code fences (:::lang ... :::) |
629+
| [myst](docs/flavors/myst.md) | MyST / Jupyter Book / Sphinx | Directives, roles, `%` comments |
630+
| [hugo](docs/flavors/hugo.md) | Hugo / Goldmark | Block attribute lists |
631+
| [mdg](docs/flavors/mdg.md) | Markdown with Gherkin | Gherkin-safe headings, tags, Doc Strings, tables |
632+
| [gh-aw](docs/flavors/gh-aw.md) | GitHub Agentic Workflows (preview) | Runtime imports and conditional directives |
632633

633634
### Configuring Flavors
634635

@@ -646,9 +647,10 @@ Or configure per-file patterns:
646647
"docs/**/*.md" = "mkdocs"
647648
"**/*.mdx" = "mdx"
648649
"**/*.qmd" = "quarto"
650+
".github/workflows/**/*.md" = "gh-aw"
649651
```
650652

651-
When no flavor is configured, rumdl auto-detects from the file name: `.mdx` → mdx, `.qmd`/`.Rmd` → quarto, `.md` → standard.
653+
When no flavor is configured, rumdl auto-detects from the file name: `.mdx` → mdx, `.qmd`/`.Rmd` → quarto, `.kramdown` → kramdown, and `.md` → standard.
652654
A name ending in `.feature.md` matches that compound suffix before the plain `.md` rule, so those files are linted as mdg.
653655

654656
For complete flavor documentation, see the [Flavors Guide](docs/flavors.md).

‎docs/comparison.md‎

Lines changed: 14 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -60,18 +60,20 @@ Most tools treat Markdown as a single dialect and rely on configuration or plugi
6060

6161
**rumdl** has built-in flavor support that adjusts rule behavior for specific documentation systems:
6262

63-
| Flavor | Target system | Example adjustments |
64-
| ------------ | --------------------- | ---------------------------------------------------------------------------- |
65-
| standard | CommonMark + GFM | Baseline behavior (GFM extensions included by default) |
66-
| mkdocs | MkDocs / Material | Admonitions, tabs, mkdocstrings |
67-
| mdx | MDX | JSX components, ESM imports |
68-
| obsidian | Obsidian | Callouts, wikilinks, Dataview |
69-
| pandoc | Pandoc Markdown | Fenced divs, attribute lists, citations, definition lists, math, grid tables |
70-
| quarto | Quarto / RMarkdown | Citations, shortcodes, executable blocks |
71-
| kramdown | Jekyll / kramdown | Attribute lists, TOC markers |
72-
| azure_devops | Azure DevOps wikis | Colon code fences (`:::mermaid … :::`) treated as opaque code blocks |
73-
| myst | MyST / Jupyter Book | Directives (`:::{name}`), roles (`` {role}`text` ``), `%` comments |
74-
| mdg | Markdown with Gherkin | Gherkin-safe headings, tag lines, Doc String fences, indented tables |
63+
| Flavor | Target system | Example adjustments |
64+
| ------------ | ---------------------------------- | ---------------------------------------------------------------------------- |
65+
| standard | CommonMark + GFM | Baseline behavior (GFM extensions included by default) |
66+
| mkdocs | MkDocs / Material | Admonitions, tabs, mkdocstrings |
67+
| mdx | MDX | JSX components, ESM imports |
68+
| obsidian | Obsidian | Callouts, wikilinks, Dataview |
69+
| pandoc | Pandoc Markdown | Fenced divs, attribute lists, citations, definition lists, math, grid tables |
70+
| quarto | Quarto / RMarkdown | Citations, shortcodes, executable blocks |
71+
| kramdown | Jekyll / kramdown | Attribute lists, TOC markers |
72+
| azure_devops | Azure DevOps wikis | Colon code fences (`:::mermaid … :::`) treated as opaque code blocks |
73+
| myst | MyST / Jupyter Book | Directives (`:::{name}`), roles (`` {role}`text` ``), `%` comments |
74+
| hugo | Hugo / Goldmark | Block attribute lists |
75+
| mdg | Markdown with Gherkin | Gherkin-safe headings, tag lines, Doc String fences, indented tables |
76+
| gh-aw | GitHub Agentic Workflows (preview) | Runtime imports, conditionals, frontmatter message templates |
7577

7678
Note: `gfm`, `github`, and `commonmark` are accepted as aliases for `standard` since the parser includes GFM extensions by default.
7779

‎docs/flavors.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ rumdl supports multiple Markdown flavors to accommodate different documentation
2222
| [myst](flavors/myst.md) | MyST / Jupyter Book / Sphinx | MD013, MD031, MD038, MD040, MD046, MD048 |
2323
| [hugo](flavors/hugo.md) | Hugo / Goldmark | MD022, MD031, MD058 |
2424
| [mdg](flavors/mdg.md) | Markdown with Gherkin | MD003, MD013, MD022, MD026, MD034, MD040, MD046, MD048, MD055, MD060, MD063 |
25+
| [gh-aw](flavors/gh-aw.md) | GitHub Agentic Workflows (preview) | MD034, MD041, MD057 |
2526

2627
## Configuration
2728

@@ -43,6 +44,7 @@ Override flavor for specific file patterns:
4344
"docs/**/*.md" = "mkdocs"
4445
"**/*.mdx" = "mdx"
4546
"**/*.qmd" = "quarto"
47+
".github/workflows/**/*.md" = "gh-aw"
4648
```
4749

4850
### Auto-Detection
@@ -81,6 +83,7 @@ The `standard` flavor includes CommonMark plus widely-adopted GFM extensions (ta
8183
- **[MyST](flavors/myst.md)** - Directives (`:::{name}`, `` ```{name} ``), roles (`{role}`content``), `%` comments
8284
- **[Hugo](flavors/hugo.md)** - Goldmark Markdown attributes (`{class="a" id="b"}`) attached to tables, headings, and code blocks
8385
- **[Markdown with Gherkin](flavors/mdg.md)** - Structure headings, tag lines, Doc String fences, and indented Gherkin tables kept in the form Gherkin accepts
86+
- **[GitHub Agentic Workflows](flavors/gh-aw.md)** - Frontmatter templates, runtime imports, and conditional control lines preserved safely (preview)
8487

8588
## Adding Flavor Support
8689

‎docs/flavors/gh-aw.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
description: "Lint GitHub Agentic Workflows while preserving frontmatter templates, runtime imports, and conditional control directives."
3+
---
4+
5+
# GitHub Agentic Workflows
6+
7+
**Config name**: `gh-aw`
8+
9+
The `gh-aw` flavor supports Markdown workflow sources compiled by
10+
[GitHub Agentic Workflows](https://github.github.com/gh-aw/). It is preview
11+
support while the upstream format remains in public preview.
12+
13+
## Configure workflow files
14+
15+
GitHub Agentic Workflows use ordinary `.md` files, so rumdl does not
16+
auto-detect this flavor. Assign it explicitly to the workflow directory:
17+
18+
```toml
19+
[per-file-flavor]
20+
".github/workflows/**/*.md" = "gh-aw"
21+
```
22+
23+
For a repository containing only Agentic Workflow Markdown, it can instead be
24+
the global flavor:
25+
26+
```toml
27+
[global]
28+
flavor = "gh-aw"
29+
```
30+
31+
The CLI accepts the same canonical name:
32+
33+
```bash
34+
rumdl check --flavor gh-aw .github/workflows/
35+
```
36+
37+
## Recognized control directives
38+
39+
rumdl recognizes these complete, standalone control lines:
40+
41+
```markdown
42+
{{#if github.event.issue.pull_request}}
43+
{{/if}}
44+
{{#elseif experiments.output_format == "detailed"}}
45+
{{#else-if experiments.output_format == "detailed"}}
46+
{{#else_if experiments.output_format == "detailed"}}
47+
{{elseif experiments.output_format == "detailed"}}
48+
{{else-if experiments.output_format == "detailed"}}
49+
{{else_if experiments.output_format == "detailed"}}
50+
{{#else}}
51+
{{else}}
52+
{{#endif}}
53+
{{#runtime-import ./shared.md}}
54+
{{#runtime-import? ./optional.md}}
55+
{{#import ./legacy.md}}
56+
```
57+
58+
Both `{{/if}}` and `{{#endif}}` close a conditional. Current gh-aw runtimes
59+
also accept the listed `elseif` spellings and the `#else`/`else` fallback
60+
forms. `runtime-import?` is the optional import form. The older `import` helper remains
61+
recognized so lint fixes do not corrupt workflows that have not yet migrated to
62+
`runtime-import`.
63+
64+
Recognition is deliberately exact. A directive name embedded in prose,
65+
unsupported helpers, malformed directives, and GitHub Actions expressions such
66+
as `${{ github.ref }}` remain ordinary Markdown and are linted normally.
67+
68+
## Rule adjustments
69+
70+
| Rule | `gh-aw` behavior |
71+
| ---- | ---------------- |
72+
| [MD034](../md034.md) | Does not report or rewrite URLs and email-like text on a recognized control line. Body prose is still checked. |
73+
| [MD041](../md041.md) | Skips leading control lines when finding the first content heading. A fix can relevel a heading in place but never moves it across a control boundary. |
74+
| [MD057](../md057.md) | Markdown-looking YAML strings are not treated as body links, and output placeholders such as `{run_url}` are not filesystem paths. Broken body links are still reported. Explicit `check-frontmatter` validation remains available for standalone path-shaped values. |
75+
76+
Paragraph reflow already treats standalone template directives as structural
77+
boundaries. The flavor's regression corpus verifies that formatting leaves all
78+
recognized control lines byte-for-byte unchanged and converges in one pass.
79+
80+
## Scope
81+
82+
The flavor makes Markdown linting and formatting safe around gh-aw syntax. It
83+
does not validate workflow frontmatter schemas, evaluate conditionals, resolve
84+
imports, or compile workflows. Use the gh-aw tooling for those operations.
85+
86+
## Learn more
87+
88+
- [Workflow structure](https://github.github.com/gh-aw/reference/workflow-structure/)
89+
- [Templating](https://github.github.com/gh-aw/reference/templating/)
90+
- [Releases and compatibility](https://github.github.com/gh-aw/reference/releases/)
91+
- [Flavors overview](../flavors.md)

‎docs/global-settings.md‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ respect-gitignore = false
7676
# Set global line length (used by MD013 and other line-length rules)
7777
line-length = 120
7878

79-
# Set markdown flavor (standard, gfm, mkdocs, mdx, pandoc, quarto, obsidian, kramdown, azure_devops, mdg)
79+
# Set markdown flavor (standard, gfm, mkdocs, mdx, pandoc, quarto, obsidian, kramdown, azure_devops, myst, hugo, mdg, gh-aw)
8080
flavor = "mkdocs"
8181

8282
# Per-file flavor overrides (pattern → flavor)
@@ -912,11 +912,18 @@ flavor = "mkdocs" # Use MkDocs flavor
912912
- `"gfm"`: GitHub Flavored Markdown with security-sensitive HTML warnings and extended autolinks
913913
- `"mkdocs"`: MkDocs-specific extensions (admonitions, content tabs, autorefs, mkdocstrings)
914914
- `"mdx"`: MDX with JSX components, attributes, expressions, and ESM imports
915+
- `"pandoc"`: Pandoc Markdown with fenced divs, attributes, citations, and definition lists
915916
- `"quarto"`: Quarto/RMarkdown for scientific publishing (citations, shortcodes, div blocks)
917+
- `"obsidian"`: Obsidian notes with callouts, wikilinks, and Dataview syntax
918+
- `"kramdown"`: Jekyll/kramdown attribute lists and extension blocks
916919
- `"azure_devops"`: Azure DevOps wikis — treats `:::mermaid` blocks as opaque code fences
920+
- `"myst"`: MyST/Jupyter Book directives, roles, math, and comments
921+
- `"hugo"`: Hugo/Goldmark block attribute lists
917922
- `"mdg"`: Markdown with Gherkin — steers headings, Doc String fences, and Gherkin tables toward the one spelling Gherkin accepts, and withholds corrections that are not safe
923+
- `"gh-aw"`: GitHub Agentic Workflows — preserves runtime imports, conditionals, and Markdown-looking message templates (preview)
918924

919-
**Aliases**: `"commonmark"` is an alias for `"standard"`, `"github"` for `"gfm"`, `"azure"` and `"ado"` for `"azure_devops"`, and `"markdown_with_gherkin"` for `"mdg"`
925+
**Aliases**: `"gfm"`, `"commonmark"`, and `"github"` map to `"standard"`; `"qmd"`, `"rmd"`, and `"rmarkdown"` map to `"quarto"`; `"jekyll"` maps to `"kramdown"`; `"azure"` and `"ado"` map to
926+
`"azure_devops"`; `"mystmd"` maps to `"myst"`; `"goldmark"` maps to `"hugo"`; and `"markdown_with_gherkin"` maps to `"mdg"`
920927

921928
**Behavior**:
922929

@@ -934,6 +941,7 @@ flavor = "mkdocs" # Use MkDocs flavor
934941
- Use `quarto` for scientific documents with R/Python code execution
935942
- Use `azure_devops` (or `azure` / `ado`) for Azure DevOps wiki content with `:::mermaid` blocks
936943
- Use `mdg` (or `markdown_with_gherkin`) for Markdown with Gherkin; files whose name ends in `.feature.md` are detected automatically
944+
- Use `gh-aw` for GitHub Agentic Workflow sources; ordinary `.md` files are not auto-detected, so prefer a `.github/workflows/**/*.md` per-file mapping
937945

938946
**Example CLI usage**:
939947

@@ -956,6 +964,7 @@ Specifies Markdown flavors for specific files or file patterns. This allows diff
956964
"**/*.mdx" = "mdx"
957965
"**/*.qmd" = "quarto"
958966
"examples/**/*.md" = "standard"
967+
".github/workflows/**/*.md" = "gh-aw"
959968
```
960969

961970
**Available Flavors**:
@@ -965,8 +974,15 @@ Specifies Markdown flavors for specific files or file patterns. This allows diff
965974
- `"commonmark"`: Alias for standard
966975
- `"mkdocs"`: MkDocs-specific extensions (auto-references, admonitions)
967976
- `"mdx"`: MDX flavor with JSX and ESM support
977+
- `"pandoc"`: Pandoc Markdown
968978
- `"quarto"`: Quarto/RMarkdown for scientific publishing
979+
- `"obsidian"`: Obsidian notes
980+
- `"kramdown"` or `"jekyll"`: Jekyll/kramdown content
981+
- `"azure_devops"`, `"azure"`, or `"ado"`: Azure DevOps wikis
982+
- `"myst"` or `"mystmd"`: MyST/Jupyter Book content
983+
- `"hugo"` or `"goldmark"`: Hugo/Goldmark content
969984
- `"mdg"` or `"markdown_with_gherkin"`: Markdown with Gherkin feature files (`.feature.md`)
985+
- `"gh-aw"`: GitHub Agentic Workflow sources (`.md`; explicit mapping required)
970986

971987
**Behavior**:
972988

‎docs/javascripts/rumdl.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@
1919
outcome: ["clean", "remaining", "unchanged"],
2020
},
2121
playground_config: {
22-
flavor: ["standard", "mkdocs", "mdx", "pandoc", "quarto", "obsidian", "kramdown", "azure_devops", "myst", "hugo", "mdg"],
22+
flavor: ["standard", "mkdocs", "mdx", "pandoc", "quarto", "obsidian", "kramdown", "azure_devops", "myst", "hugo", "mdg", "gh-aw"],
2323
disabled: ["0", "1", "2_4", "5_plus"],
2424
line_length: ["under_80", "80", "81_120", "over_120"],
2525
},

‎docs/markdownlint-comparison.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -248,6 +248,7 @@ the [flavors guide](flavors.md).
248248
| `myst` | MyST / Jupyter Book / Sphinx | Directives, roles, `%` comments |
249249
| `hugo` | Hugo / Goldmark | Block attribute lists |
250250
| `mdg` | Markdown with Gherkin | Gherkin-safe headings, tags, and tables |
251+
| `gh-aw` | GitHub Agentic Workflows (preview) | Runtime imports and conditional controls |
251252

252253
**Configuration:**
253254

‎docs/md034.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,14 @@ for content where a bare URL or email address is the required spelling.
8686
See [Markdown with Gherkin Flavor](flavors/mdg.md) for the full flavor
8787
specification.
8888

89+
## GitHub Agentic Workflows
90+
91+
Under the `gh-aw` flavor, MD034 skips complete, recognized gh-aw control lines.
92+
For example, it leaves a URL inside `{{#runtime-import https://example.com/shared.md}}`
93+
unchanged because inserting angle brackets would corrupt the template syntax.
94+
URLs in workflow body prose are still reported and fixed normally. See the
95+
[GitHub Agentic Workflows flavor](flavors/gh-aw.md) for the exact directive set.
96+
8997
## Learn more
9098

9199
- [CommonMark autolinks](https://spec.commonmark.org/0.31.2/#autolinks) - Technical specification for URL formatting

0 commit comments

Comments
 (0)