gastro/docs/ at main · andri.dk/gastro · Tangled

andri.dk / gastro

0

[READ-ONLY] Mirror of https://github.com/andrioid/gastro. Server Side templates, combining Go (frontmatter) and html/template (body) with full LSP support gastro.andri.dk

golang lsp-server template-engine

0

gastro / docs

1 folder 17 files

at main

Andri Óskarsson docs: document attribute forwarding (attrs, twJoin/twMerge, WithClassMerger) 4w ago

docs(history): archive drop-markdown-directive plan as executed Plan moved from tmp/ to docs/history/ per the convention used by the prerequisite frontmatter-package-scope plan. Status block updated to record the five-commit execution chain on feat/drop-markdown-directive plus the Phase 7 verification outcome (tests, lint, per-example builds, bootstrap, smoke, go.sum audit all green).

2 months ago

architecture.md

docs: document attribute forwarding (attrs, twJoin/twMerge, WithClassMerger) Documents the attribute-forwarding feature: a Forwarding attributes section in components.md (gastro.Attrs, the attrs func, escaping/bypass, bool attrs, class merge, WithClassMerger, the typo-becomes-attribute tradeoff), an Attribute Forwarding section in helpers.md covering attrs/twJoin/twMerge, and WithClassMerger in the README option list. Refs #37.

1 month ago

docs: secondary touch-ups for Track B Adopter-facing docs updated to match Track B's page model. The primary rewrites (pages, sse, design \u00a721) shipped in the previous commit; this commit aligns the remaining shorter mentions so adopters reading any entry point see consistent guidance. README.md: replace the ctx-anchored Variable Visibility example with one that uses r.PathValue. Add a note that frontmatter has ambient (w, r) and the page handler runs for every method. Update the File-Based Routing table to method-less patterns and explain why. docs/components.md: drop the orphaned ctx := gastro.Context() line in the import-and-use example; the example doesn't need it and pages that import components no longer carry the marker by default. docs/architecture.md: realign the AnalyzeFrontmatter responsibilities, the GenerateHandler description, and the data-flow diagram with the Track B implementation. The diagram now shows a page using r.PathValue and notes that FrontmatterInfo carries marker / missing- return warnings. The new marker-rewrite allowlist is documented as a table inline with the codegen description. docs/comparison.md: update the Learning Curve row to drop gastro.Context() and lead with ambient (w, r). dev-mode.md and getting-started.md needed no changes \u2014 neither referenced gastro.Context() in the first place.

2 months ago

docs: document attribute forwarding (attrs, twJoin/twMerge, WithClassMerger) Documents the attribute-forwarding feature: a Forwarding attributes section in components.md (gastro.Attrs, the attrs func, escaping/bypass, bool attrs, class merge, WithClassMerger, the typo-becomes-attribute tradeoff), an Attribute Forwarding section in helpers.md covering attrs/twJoin/twMerge, and WithClassMerger in the README option list. Refs #37.

1 month ago

docs: surface New(), WithDeps, WithOverride, gastro check across docs The README, sse, helpers, compression, and architecture docs still showed gastro.Routes() as the primary entry point. Updated them to prefer gastro.New(opts...).Handler() while noting Routes() remains as a deprecated shim. Specific changes: - README.md: 'Custom helpers' example uses gastro.New(); short explanation of New() / WithDeps / WithOverride with cross-links. - docs/sse.md: 'Wiring It Up' main.go uses gastro.New() and includes a one-paragraph note on why New() is preferred over Routes(). - docs/helpers.md: WithFuncs example uses gastro.New(). - docs/compression.md: GzipMiddleware and gzhttp examples wrap router.Handler() and the dev-mode-composition note matches. - docs/architecture.md: '*Router type, New() constructor, methods on Router' replaces the old 'Routes() function' description of routes.go. The website (examples/gastro) renders these markdown files directly via the {{ markdown }} helper, so it picks up the changes without any .gastro file edits. Smoke-tested by running the site locally and curling each affected page. The original Design Document (docs/design.md) is left as-is per its historical-record purpose.

3 months ago

contributing.md

fix(examples/gastro): use `go tool gastro` in //go:generate CI failed on the post-migration drift gate with: generate.go:22: running "gastro": exec: "gastro": executable file not found in $PATH The mise-action adds the standalone tailwindcss binary to PATH but doesn't install `gastro` (it's not declared in mise.toml \u2014 the website is self-hosting). The example's go.mod already declares `tool github.com/andrioid/gastro/cmd/gastro`, so switching the directive to `go tool gastro generate` resolves the binary through the tool directive and works in CI without any extra setup. Local mise-activated shells continue to work because `go tool` is a strict superset of having `gastro` on PATH. Also corrects the matching reference in docs/contributing.md.

2 months ago

docs: surface gastro fmt, naming rule, build loop, and From accessor Adds an llms.txt primer and documents the greenfield friction from #36: generate-before-build, the filename->identifier derivation rule, gastro fmt vs gofmt, go generate ordering, and the prune behavior. Also corrects stale doc comments in pkg/gastro/deps.go that referenced the removed From accessor. Refs #36.

1 month ago

docs: refresh stale embed/CLI claims in README and design.md Two outdated claims in user-facing docs: README.md "Deployment" — the "//go:embed is designed but not yet wired into the compiler" note was stale. Embedding has been wired for some time: internal/compiler/compiler.go emits //go:embed templates/* and //go:embed static/* directives, with dev/prod switching via GASTRO_DEV (pkg/gastro/fs.go's GetTemplateFS / GetStaticFS). docs/design.md \xa71 already lists Embedding as Done. Rewrote the paragraph to describe what actually happens: prod binaries are self-contained, dev mode reads from disk for hot reload. docs/design.md \xa713 CLI — the table listed only generate/build/dev and marked `gastro new` as "Future: not yet implemented". `gastro new` ships (cmd/gastro/main.go:75), as do watch, fmt, check, list, lsp, and version. Replaced the truncated list with the full set actually shown by `gastro --help`.

2 months ago

feat(cli): --asset CMD on gastro watch (reload-aware build chain) Adds a `--asset CMD` (alias `-a`) flag to `gastro watch` for content-derived asset generators that need to re-run on every change, not just restart-class changes. Closes the gap that made Tailwind silently miss new utility classes on template-body edits. Why it matters -------------- A template-body edit (e.g. adding `class="size-12"` to a div) is RELOAD-class per `internal/watcher/watcher.go`: the running binary keeps serving and devloop fires `OnReload` to refresh the browser. The existing `--build` chain runs only in the `OnRestart` path, so a Tailwind step placed in `--build` is silently skipped on every body-only edit. Browser refreshes with stale CSS; new class does nothing. Touching frontmatter or restarting the dev server were the only workarounds. What changed ------------ internal/devloop/devloop.go - New `Config.PreReload func(ctx) error` hook. Runs between `Generate` and `OnReload` on reload-class changes only. Returning a non-nil error suppresses the OnReload signal for that cycle so the browser doesn't refresh onto a half-rebuilt asset state. - Three new tests: ordering (pre-reload precedes on-reload), error-suppresses-reload, nil-preserves-behaviour. cmd/gastro/watch.go - New `--asset CMD` / `-a CMD` flag (repeatable, mirrors --build). - Extract build-execution into a shared `runChain(ctx, label, cmds)` helper so --build and --asset have identical failure semantics and the same `.gastro/.build-error` writeback. - On RESTART-class: asset chain runs first, then build chain, then the app restarts. - On RELOAD-class: asset chain runs via PreReload, then the reload signal fires. - Output-collision warning at L323 extended to --asset. - `gastro dev` flag-rejection message updated to mention --asset. - --help text documents both flags side-by-side with a NOTE on the RESTART-only semantics of --build. - 5 new parser tests + 2 new integration tests. scripts/dev/example-website - Migrate `tailwindcss` from --build to --asset. Comment expanded to explain why (RELOAD-class miss is the bug we're fixing). docs/dev-mode.md - New "Asset chain vs build chain" subsection with a two-row decision table and a worked Tailwind example. DECISIONS.md - Per-commit decision entry covering the bug, alternatives weighed, and what is/isn't in scope. What this is not ---------------- - Not a Tailwind integration; --asset is generic over any shell command. - Not a change to ClassifyChange; body edits stay RELOAD-class so the optimization that makes them feel instant is preserved. - Not a `gastro dev` feature; the zero-config dev path stays zero-config. Users who need asset pipelines reach for `gastro watch`, which is the documented escape hatch. Tests ----- All `go test -race ./...` green. 10 new tests total: 3 devloop unit, 5 cli parser, 2 cli integration.

2 months ago

error-handling.md

docs(plan): archive frictions plan — Wave 5 closed (Q4 audit drops A2) Q4 audit ("does //go:embed at source dirs change gastro dev path resolution?") revealed A2 itself is infeasible: .gastro/templates/*.html are not copies of source .gastro files but the transformed template body (frontmatter stripped, markdown directives expanded, {{ wrap }} rewritten to compiled component calls, filenames flattened). Embedding raw .gastro source would not parse via html/template; recovering the parseable shape at runtime would require re-running codegen on every dev request. The originally-stated benefit ("cuts the embed half of the committed tree") is also obsolete: .gastro/ is gitignored by default at the repo root and in the scaffold; git ls-files | grep '\.gastro/' returns zero tracked files. For downstream commit-the-tree teams, the per-project remedy is to add .gastro/templates/ to their own .gitignore — documented in a new docs/deployment.md "Trimming the committed tree" subsection. With Wave 5 closed empty (A2 dropped, A6 already dropped per Q5) and all other waves and Track B shipped, the working plan is archived: plans/frictions-plan.md → docs/history/frictions-plan.md plans/frictions-mode-split.html → docs/history/frictions-mode-split.html frictions.md → docs/history/frictions.md The empty plans/ directory was removed. Live code-comment and doc references updated to the new paths (24 sites across pkg/, internal/, examples/, docs/). Historical DECISIONS.md entries left alone — they're a dated log of paths-as-of-that-date and rewriting them would falsify the record. Examples regenerated to clear pre-existing codegen drift; all four pass gastro check. Full -race test suite green.

2 months ago

getting-started-library.md

docs: document //gastro:embed and the user-side markdown story Phase 6: refresh the docs to reflect the new model where the framework provides codegen-time //gastro:embed and the user provides the markdown renderer. New docs/markdown.md (~200 lines): - 'Why no built-in helper?' rationale. - 30-line copy-pasteable goldmark+chroma renderer (the same one examples/gastro/md/md.go ships). - Static markdown pattern (//gastro:embed + md.MustRender at init). - Directive contract: relative paths, module-boundary semantics (with a note that user-placed symlinks are followed even when the target sits outside the module — the monorepo escape hatch). - Two foot-guns: per-request waste (':=') and init-time panic ('MustRender'), with a CI smoke recommendation. - Dynamic markdown pattern (slug-based blog post via embed.FS + md.Render per request). - Mental-model table covering static / dynamic-from-FS / dynamic -from-DB cases. - Pointer to the future sub-module ('there isn't one yet; file an issue if you need one'). Updated existing docs: - docs/dev-mode.md, docs/getting-started-library.md: replace the stale '{{ markdown ... }}' phrasing with '//gastro:embed' in the watcher-surface descriptions. - docs/architecture.md: rewrite ExternalDeps prose for the new semantics; replace the ProcessMarkdownDirectives stage in the pipeline diagram with ProcessEmbedDirectives plus the new 'user code renders bytes' note. - docs/deployment.md: update the build-artefacts paragraph to explain that //gastro:embed bakes content into the generated .go files at codegen time, not into templates. - docs/pages.md: cross-link to docs/markdown.md from the package- scope frontmatter section. - docs/components.md: cross-link to docs/markdown.md from the pre-rendering table. - README.md: add docs/markdown.md to the Documentation list. - internal/lsp/shadow/workspace_test.go (line 683): refresh the comment that mentioned 'all transitive runtime dependencies (chroma, goldmark, etc.)' to reflect the new position.

2 months ago

getting-started.md

docs: surface gastro fmt, naming rule, build loop, and From accessor Adds an llms.txt primer and documents the greenfield friction from #36: generate-before-build, the filename->identifier derivation rule, gastro fmt vs gofmt, go generate ordering, and the prune behavior. Also corrects stale doc comments in pkg/gastro/deps.go that referenced the removed From accessor. Refs #36.

1 month ago

docs: document attribute forwarding (attrs, twJoin/twMerge, WithClassMerger) Documents the attribute-forwarding feature: a Forwarding attributes section in components.md (gastro.Attrs, the attrs func, escaping/bypass, bool attrs, class merge, WithClassMerger, the typo-becomes-attribute tradeoff), an Attribute Forwarding section in helpers.md covering attrs/twJoin/twMerge, and WithClassMerger in the README option list. Refs #37.

1 month ago

docs: full WithRequestFuncs documentation pass + DECISIONS entry Phase 5d (remaining). Completes the docs surface for the WithRequestFuncs feature now that all three example apps are in place. - docs/i18n.md (new, ~280 lines): full recipe walking through the examples/i18n/ app step-by-step. Covers library choice, embed layout, locale-detection middleware shapes (path / cookie / Accept-Language / fallback), the WithRequestFuncs binder, template usage, the xgettext translation workflow, CLDR plural rules (and when to reach for gotext), and the per-page-frontmatter alternative for content-light pages. - docs/sse.md: new "Request-aware helpers in SSE patches" subsection documenting Render.With(r) as the SSE-handler counterpart to the request-aware page render path. Calls out the reusable-within-a-request lifetime contract (D4). - docs/helpers.md: "Known limitation: components called from templates" section replaced with "Components, slots, and wrap blocks" \u2014 the limitation is no longer a limitation (nested propagation shipped in the previous commit). The "Worked example" section now points at all three examples/ apps with a comparison table of the axes each one stresses. - README.md: WithRequestFuncs called out in the options list next to WithFuncs / WithDeps / WithMiddleware / WithErrorHandler with a forward-link to docs/helpers.md. - DECISIONS.md: comprehensive entry recording the eight resolved decisions (D1\u2013D8 from tmp/withrequestfuncs-plan.md \u00a710), the rejected alternatives (pkg/gastro/i18n, pkg/gastro/csrf, pkg/gastro/csp helper packages; gastro i18n extract CLI; markdownLocalized directive; langPath framework helper; per-locale pre-parse), and a phase-by-phase implementation summary across both PRs. Refs: tmp/withrequestfuncs-plan.md \u00a75d.

2 months ago

feat(examples): mermaid diagram support in markdown renderer Add a small goldmark extension to the example site's md package that renders fenced ```mermaid blocks as <pre class="mermaid"> elements, plus a lazy mermaid.js loader in the base layout that only fetches the library when a diagram is present on the page. The extension uses a parser-stage AST transformer to swap mermaid fenced blocks for a custom node kind before goldmark-highlighting's chroma renderer sees them, so the two extensions don't compete for FencedCodeBlock rendering. No new Go dependencies — composes the goldmark sub-packages already pulled in for syntax highlighting. Also: - Demo flowchart in docs/sse.md showing the GET vs POST page lifecycle. - New 'Mermaid diagrams' section in docs/markdown.md documenting the pattern, the lazy-loader snippet, and the HTML-escape + securityLevel:'strict' trust boundary. - Tests covering mermaid passthrough, adjacent code blocks still reaching chroma, and HTML escaping of <script> inside diagrams.

2 months ago

pages-v2-migration.md

docs(plan): archive frictions plan — Wave 5 closed (Q4 audit drops A2) Q4 audit ("does //go:embed at source dirs change gastro dev path resolution?") revealed A2 itself is infeasible: .gastro/templates/*.html are not copies of source .gastro files but the transformed template body (frontmatter stripped, markdown directives expanded, {{ wrap }} rewritten to compiled component calls, filenames flattened). Embedding raw .gastro source would not parse via html/template; recovering the parseable shape at runtime would require re-running codegen on every dev request. The originally-stated benefit ("cuts the embed half of the committed tree") is also obsolete: .gastro/ is gitignored by default at the repo root and in the scaffold; git ls-files | grep '\.gastro/' returns zero tracked files. For downstream commit-the-tree teams, the per-project remedy is to add .gastro/templates/ to their own .gitignore — documented in a new docs/deployment.md "Trimming the committed tree" subsection. With Wave 5 closed empty (A2 dropped, A6 already dropped per Q5) and all other waves and Track B shipped, the working plan is archived: plans/frictions-plan.md → docs/history/frictions-plan.md plans/frictions-mode-split.html → docs/history/frictions-mode-split.html frictions.md → docs/history/frictions.md The empty plans/ directory was removed. Live code-comment and doc references updated to the new paths (24 sites across pkg/, internal/, examples/, docs/). Historical DECISIONS.md entries left alone — they're a dated log of paths-as-of-that-date and rewriting them would falsify the record. Examples regenerated to clear pre-existing codegen drift; all four pass gastro check. Full -race test suite green.

2 months ago

docs: document //gastro:embed and the user-side markdown story Phase 6: refresh the docs to reflect the new model where the framework provides codegen-time //gastro:embed and the user provides the markdown renderer. New docs/markdown.md (~200 lines): - 'Why no built-in helper?' rationale. - 30-line copy-pasteable goldmark+chroma renderer (the same one examples/gastro/md/md.go ships). - Static markdown pattern (//gastro:embed + md.MustRender at init). - Directive contract: relative paths, module-boundary semantics (with a note that user-placed symlinks are followed even when the target sits outside the module — the monorepo escape hatch). - Two foot-guns: per-request waste (':=') and init-time panic ('MustRender'), with a CI smoke recommendation. - Dynamic markdown pattern (slug-based blog post via embed.FS + md.Render per request). - Mental-model table covering static / dynamic-from-FS / dynamic -from-DB cases. - Pointer to the future sub-module ('there isn't one yet; file an issue if you need one'). Updated existing docs: - docs/dev-mode.md, docs/getting-started-library.md: replace the stale '{{ markdown ... }}' phrasing with '//gastro:embed' in the watcher-surface descriptions. - docs/architecture.md: rewrite ExternalDeps prose for the new semantics; replace the ProcessMarkdownDirectives stage in the pipeline diagram with ProcessEmbedDirectives plus the new 'user code renders bytes' note. - docs/deployment.md: update the build-artefacts paragraph to explain that //gastro:embed bakes content into the generated .go files at codegen time, not into templates. - docs/pages.md: cross-link to docs/markdown.md from the package- scope frontmatter section. - docs/components.md: cross-link to docs/markdown.md from the pre-rendering table. - README.md: add docs/markdown.md to the Documentation list. - internal/lsp/shadow/workspace_test.go (line 683): refresh the comment that mentioned 'all transitive runtime dependencies (chroma, goldmark, etc.)' to reflect the new position.

2 months ago

docs: full WithRequestFuncs documentation pass + DECISIONS entry Phase 5d (remaining). Completes the docs surface for the WithRequestFuncs feature now that all three example apps are in place. - docs/i18n.md (new, ~280 lines): full recipe walking through the examples/i18n/ app step-by-step. Covers library choice, embed layout, locale-detection middleware shapes (path / cookie / Accept-Language / fallback), the WithRequestFuncs binder, template usage, the xgettext translation workflow, CLDR plural rules (and when to reach for gotext), and the per-page-frontmatter alternative for content-light pages. - docs/sse.md: new "Request-aware helpers in SSE patches" subsection documenting Render.With(r) as the SSE-handler counterpart to the request-aware page render path. Calls out the reusable-within-a-request lifetime contract (D4). - docs/helpers.md: "Known limitation: components called from templates" section replaced with "Components, slots, and wrap blocks" \u2014 the limitation is no longer a limitation (nested propagation shipped in the previous commit). The "Worked example" section now points at all three examples/ apps with a comparison table of the axes each one stresses. - README.md: WithRequestFuncs called out in the options list next to WithFuncs / WithDeps / WithMiddleware / WithErrorHandler with a forward-link to docs/helpers.md. - DECISIONS.md: comprehensive entry recording the eight resolved decisions (D1\u2013D8 from tmp/withrequestfuncs-plan.md \u00a710), the rejected alternatives (pkg/gastro/i18n, pkg/gastro/csrf, pkg/gastro/csp helper packages; gastro i18n extract CLI; markdownLocalized directive; langPath framework helper; per-locale pre-parse), and a phase-by-phase implementation summary across both PRs. Refs: tmp/withrequestfuncs-plan.md \u00a75d.

2 months ago