docs: rework intro — real multi-macro example, expanded "Why", playground#184
Merged
Merged
Conversation
…nd playground The lead example now compiles a real CI→deploy workflow that flexes three macros at once (typed params, a shared _anchors setup reused across jobs, and a retry on the deploy) instead of the single dynamic-matrix snippet. The generated YAML is the actual `actio build` output (canonical --no-annotate --no-pin expansion). Replace the thin "Why" with a "Why Actio" benefit list (zero lock-in, incremental adoption, pre-CI validation, step reuse, no runtime deps, one source/many workflows, honest output) ahead of the pain→macro table. Add a playground Callout under the example and a Playground card to Next steps. Repoint the home-page "Explore macros" button off the deprecated /docs/macros/fragments → /docs/syntax. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
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
1 participant
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.
What
The intro (
/docs) is one of our most important pages and the old version was weak: a singledynamic-matrixsnippet that didn't show off much, a thin 1-line "Why", and no mention of the playground. This reworks it.Lead example — now a real, multi-macro workflow
Swaps the lone
dynamic-matrixsnippet for a real CI→deploy workflow that flexes three macros at once:params(enumenvironment)_anchorsblock reused across both jobsretryon the flaky deploy stepThe
generated .ymlside is the actualactio buildoutput (canonical--no-annotate --no-pinexpansion), not hand-written — so it stays honest."Why" → "Why Actio"
Replaces the single lead-in sentence with 7 concise benefit bullets (zero lock-in, incremental adoption, pre-CI validation, step reuse, no runtime deps, one-source/many-workflows, honest output) ahead of the existing pain→macro table.
Playground
Calloutunder the example: try it in the browser before installing.Drive-by
/docs/macros/fragments→/docs/syntax.De-dup respected
Keeps the canonical SSOT map: links
/docs/syntax(keyword dictionary),/docs/architecture(mental model),/docs/macros/anchors(reuse),/docs/source-maps— doesn't re-enumerate any of them.Gates
npm test -- docs-completeness syntax-reference macros→ 84 passed ✅npm run docs:build→ green, all paths prerendered (incl./docs,/play) ✅Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com