docs(eql): generate per-type function tables as included partials#69
Merged
Conversation
The "Functions available on this type" tables on the numbers, text, and dates-and-times reference pages were hand-maintained and had silently drifted from the EQL surface before. Generate them from the EQL manifest instead and embed them via Fumadocs' `<include>` directive, so the per-type operator-function matrix can't drift from the catalog it documents. - generate-eql-api-docs.ts emits content/partials/eql/functions-<page>.mdx from domains[].capabilities + variant, collapsing variants per capability (e.g. all `_ord` variants) and naming them concretely for single-type pages (text_eq) vs generically for type families (_eq). - Partials live outside the content collections so Fumadocs never routes them; they're included cwd-relative and committed so dev/types:check (which skip prebuild) resolve them. - Verified: output is byte-identical to the prior hand tables against the real EQL 3.0.0 manifest; full build produces no stray routes and inlines the tables into HTML, copy-markdown, and llms output. json (bespoke containment/path functions) and booleans (storage-only) are left as hand-written prose, not part of the per-type matrix.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Replace the generated function table with a per-function layout: one card per function (lt/lte/gt/gte grouped into one), showing its operator equivalents, the domains it applies to, and a worked example. - New <EqlFn> client component renders the card, operator badges, and the applies-to domain list. The domain list shows the first two variants with a "Show all N variants" toggle, so the 24-domain numbers cases don't flood the page. Styled with Fumadocs fd-* tokens so it tracks the theme. - generate-eql-api-docs.ts emits <EqlFn> blocks into the partials, with the domain list pulled from the manifest (drift-proof). The example is passed as the code-fence child so it keeps the site's highlighting and copy button; examples are templated by capability — the one authored part. - Text ordering functions demonstrate ORDER BY (sorting is the point on text); numbers/dates keep the range form. contains/contained_by only render where a match-capable domain exists, so they're absent on numbers and dates. Verified: full build renders every card, operators, pills, and highlighted examples with no stray tags; types:check and lint pass.
- Remove the worked example from each function card; each page's own "Example queries" section already covers examples, so the per-card ones only duplicated them. <EqlFn> no longer takes children. - Add a stable anchor id per function (fn-eq, fn-comparison, …) with a hover link affordance, so individual functions are deep-linkable. - Drop the accent border/tint on the grouped comparison card; every card now uses the same neutral card styling.
…s section Correcting the previous commit, which removed the examples from the wrong place. The per-function example belongs in each card; it's the page-level "## Example queries" section that was redundant with them. - Restore the worked example inside <EqlFn> (passed as children, so it keeps the site's highlighting and copy button); the generator templates it by capability again. - Remove the "## Example queries" section from the text, numbers, and dates-and-times pages — the per-function cards now carry the examples.
Each function's name is now a real `###` heading (with an explicit `[#fn-*]` id) instead of text inside the card. The table of contents only sees Markdown headings, so this lists every function as a sub-item under "Functions" in the right-hand nav, and keeps the stable deep-link anchor. The <EqlFn> card renders everything below the heading — operator equivalents (now under an "Operators"/"Aggregate" label), the applies-to domains, and the example. It no longer takes name/id props or renders its own anchor, since the heading owns both.
The JSON page's query surface (containment, field access, leaf comparisons, path queries, array helpers) was prose spread across three sections. Restructure it into a "## Functions" section of <EqlFn> cards under `###` headings, matching the scalar type pages: each function is now a TOC sub-item under Functions and a deep-link anchor. Unlike the scalar pages, JSON's functions aren't derivable from domain capabilities (the jsonb domains are storage-only), so these cards are authored directly in json.mdx rather than generated. json.mdx is scanned by the drift guard, so every eql_v3.* symbol referenced is still validated against the manifest. - Make <EqlFn>'s `ops` optional so pure functions (jsonb_path_query, the array helpers) render without an operator row. - Preserve the GIN containment index recipe and the selector-hash / typed-operand notes as prose within the new section.
Show the plaintext JSON the function examples query against, right under the Functions heading, and map the `*_selector` placeholders to their paths. Readers can see what each function operates on instead of inferring it from the selector names.
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 "Functions available on this type" tables on the numbers, text, and dates-and-times EQL reference pages were hand-maintained, and had silently drifted from the actual EQL surface in the past. This generates them from the EQL manifest and embeds them via Fumadocs' native
<include>directive, so the per-type operator-function matrix can no longer drift from the catalog it documents.How
generate-eql-api-docs.tsnow emitscontent/partials/eql/functions-<page>.mdxfrom the manifest'sdomains[].capabilities+variantfields. It collapses variants per capability (e.g._ord+_ord_ope+_ord_ore→ "all_ordvariants") and names them concretely for single-type pages (text_eq) vs. generically for type families (_eq).<include cwd>content/partials/eql/functions-<page>.mdx</include>, keeping their headings and page-specific prose hand-written.Design notes
content/partials/, notcontent/docs/). Fumadocs globs**/*.{md,mdx}into routes, so a partial inside the content tree would become a stray URL. Verified the build produces zero stray routes and inlines the tables into the HTML, the copy-markdown.body, and the llms output.bun devandtypes:checkskipprebuild, so the fragments must be on disk. They match what Vercel regenerates from the real manifest, so no drift.json(bespoke containment/path functions) andbooleans(storage-only) are left as hand-written prose — they aren't the per-type matrix that drifts.Verification
bun run buildpasses, no stray routes, tables inline correctly.validate-links,validate-content, and Biome all pass.https://claude.ai/code/session_01NkxKebM3qffTB7FayXsfxP