Project guide for Claude Code working in this repository. Tells you what this site is, how the AEO platform is wired together, where the dependencies live, and the conventions to follow.
stackql.io is the marketing and documentation site for StackQL, built on Docusaurus 3.10. Three audiences:
- Humans - default site nav. This is a docs-only site: the docs tree is the site root (
/installing-stackql,/providers,/getting-started/*,/command-line-usage/*,/mcp/*,/language-spec/*,/developers/*,/quick-starts/*) and docs/index.md is the homepage. Blog at/blog/<section>/*(three sections, see "The blog" below). Four top-level pages remain:/privacy,/termsand/support(MDX insrc/pages) and/contact-us(a React page: community channels, email, phone and address). The three MDX pages are the privacy, terms and support URLs that the ChatGPT and Claude plugin directory listings point at (issue #305), so keep those paths stable. There are no meta-refresh stub pages: every alias URL is a Netlify 301 (see "Redirects are Netlify 301s, never pages" below). - AI agents and answer engines - a parallel content surface at
/ai/*(canonical definitions, comparisons, how-tos, FAQs, troubleshooting, etc.) reachable by deep link, viallms.txtand from one "AI Reference" link in the footer, but not from the header nav. The footer link exists so the tree has a crawl path: with no internal link at all Google left its 44 sitemap URLs as "Discovered - currently not indexed". - LLM crawlers -
llms.txtandllms-full.txtat site root; a plain-markdown twin (/foo.md) for every doc and blog page, advertised from each page by<link rel="alternate" type="text/markdown">.
The two surfaces serve the same URLs to all visitors (no UA-based cloaking). The /ai/* pages just don't appear in the header nav.
Every alias or retired URL on this site is a [[redirects]] rule in netlify.toml, not a built page. Do not add a src/pages stub or a plugin route that renders <meta http-equiv="refresh">: a meta-refresh page is a 200 that the sitemap plugin lists and that Google reports as "Page with redirect" (Search Console flagged every one of them in October 2026), and it carries conflicting signals (robots: index,follow, a canonical, and a refresh). An edge 301 is neither built nor listed. The former stubs (/install, /downloads, /stackqldocs, /tutorials, /cookbooks, /stackql-deploy -> stackql-deploy.io, /features -> /, /providers/<slug>, /registry/<name>) are all rules now; the navbar and footer link to stackql-deploy.io directly. /contact-us was a stub to GitHub Discussions and is a real page now (src/pages/contact-us.js, data in src/data/contact-us/index.js): agents landing on it read contact details as text rather than an empty page.
Two blocks of rules are generated and must not be edited by hand:
BEGIN/END generated provider redirects- scripts/generate-provider-redirects.js, from the provider catalog. The pre-commit hook regenerates it whenever a commit touches src/configs/providers.json (see "Provider catalog"); run the script by hand after a--no-verifycommit.BEGIN/END generated blog redirects- scripts/generate-blog-redirects.js, from blog front matter slugs. See "The blog".
Netlify serves a matching static file in preference to a rule unless the rule has force = true, so a rule only works for a path that is not also built. If something must link to an alias path from inside the site (it should not need to), use pathname:// so onBrokenLinks: 'throw' does not reject it.
- Docusaurus 3.10.1, classic preset
- React 18 (pinned - several deps require it)
- MUI 5/6 (already in deps - Material UI and emotion)
- Node 22 toolchain, yarn is the package manager (yarn.lock is the only lockfile - package-lock.json is gitignored)
- Deployed via Netlify, build =
npm run build, publish =build/ - Search via Algolia DocSearch (
ALGOLIA_APP_ID,ALGOLIA_API_KEY,ALGOLIA_INDEX_NAMEenv vars required for prod builds)
The classic preset's docs instance has routeBasePath: '/' (Docusaurus docs-only mode). docs/index.md carries slug: / and is the homepage; there is no src/pages/index.js. The marketing homepage was collapsed into the docs site in August 2025, and until October 2026 the root was a meta-refresh stub to /docs, which is why Google indexed /docs as the home and showed no sitelinks.
- Inbound
/docs/*links are Netlify 301s to the same path without the prefix (/docs->/,/docs.md->/index.md,/docs/*->/:splat). Those rules sit below the/docs/query-library/*proxy and the specific legacy/docs/...rules in netlify.toml. Netlify applies the first matching rule, so keep that order. - The query library stays proxied at
/docs/query-library/*: it is a separate site whosebaseUrlis a cross-repo contract (see "The query library" below). It is the only thing left under/docs. - Internal links use root paths (
/installing-stackql, never/docs/installing-stackql).onBrokenLinks: 'throw'catches relative mistakes; absolutestackql.io/docs/...links need a grep. - Root-level routes that are not docs:
/blog/*,/ai/*,/privacy,/terms,/support,/contact-us,/search, and the Netlify 301 aliases (/install,/downloads,/stackqldocs,/stackql-deploy,/features,/tutorials,/cookbooks,/providers/<slug>,/registry/*). A new doc whose slug collides with one of these would clash with it (a built file shadows a Netlify rule), so check before adding root-level docs. - Getting Started and Command Line Usage are sidebar categories with generated index pages (
/getting-started,/command-line-usage), so every major section has a landing page Google can surface as a sitelink: installation, providers, getting started, command line usage, MCP.
The site is built once per locale from i18nConfig in docusaurus.config.js: en at the root and every other locale under its own path: de at /de/, es at /es/, fr at /fr/, id at /id/, ja at /ja/, ko at /ko/, pt-BR at /pt-br/, vi at /vi/ and zh-Hans at /zh-hans/ today; pl is planned. It is standard Docusaurus i18n (i18n/<locale>/<plugin name>[-<instance id>]/..., locale dropdown, hreflang and og:locale per page, one SPA and one sitemap per locale) with these site-specific pieces:
- What is translated is per locale, in scripts/i18n/config.js (
locales.<l>.sources):de,es,fr,id,ja,ko,pt-BRandvitranslatedocsonly;zh-Hanstranslatesdocsandai-content. The AI Reference (ai-content) exists for answer engines, whose crawlers read English and Chinese, so it is translated forzh-Hansonly; the blog and the three MDX pages undersrc/pagesare not translated in any locale. Anything not translated is served in English at the localized URL (Docusaurus falls back to the default locale) and markednoindexby the wrappers in src/theme/DocItem/Content, src/theme/BlogPostPage, src/theme/BlogListPage, src/theme/BlogArchivePage and the blog landing page. The fallback is detected frommetadata.source: a translated page's source is under@site/i18n/(src/lib/i18n.js). A translated doc shows a "Translated page" notice linking to the English page;hide_translation_notice: truein the front matter hides it. - What crawlers get per locale follows from what is translated: every locale has its own
sitemap.xml,llms.txt,llms-full.txtand.mdcompanions, and each covers only the pages that exist in that language. English and Simplified Chinese are the languages of the search engines and model labs the site targets, so they carry the full surface including the AI Reference; a locale such asde,es,fr,id,ja,ko,pt-BRorvicosts nothing extra and publishes the same files for its translated docs only. The rule that matters is that no English copy of an untranslated page is published under/<locale>/where it would compete with the English original: before November 2026/de/llms.txtlisted 321 pages of which about 155 were English (the AI Reference and every blog post), each with an indexable.md. The sitemap needs no configuration (untranslated pages are noindex and the sitemap plugin leaves noindex pages out). For the answer engine files,configForLocale()at the end of docusaurus.config.js readslocales.<l>.sourcesfrom scripts/i18n/config.js and adds the routes of the untranslated source sets (/ai/**,/blog/<section>/**) to the AEO plugin'scompanions.exclude;llms.txtandllms-full.txtare built from the companions, so they follow, and the Ask AI button only shows on pages that have a companion. It also drops the footer "AI Reference" link for a locale the AI Reference is not translated for. The config is exported as a function for this:docusaurus buildsetsDOCUSAURUS_CURRENT_LOCALEbefore loading the config for each locale, but the module is evaluated once per process, so a top-level read of that variable keeps the first locale's value for every locale (the exported function is called on every load). static/robots.txt lists one sitemap per locale by hand, and netlify.toml repeats the/llms.txtand/llms-full.txtheader rules per locale. - Translations are generated by Claude Code, interactively or headless, following .claude/skills/i18n-translate/SKILL.md and i18n/glossary.md (terminology and style per locale). Text only: code fences (SQL, commands, mermaid diagrams), inline code, links, imports, JSX and images are never translated, and images are shared by every locale. Every heading in
docs/andai-content/carries an explicit{#id}(yarn write-heading-ids . docs ai-content, rerun for new pages) so anchors are identical in every locale;onBrokenAnchors: 'throw'enforces it. The exception is a heading indented inside a JSX block (the## macOSheadings inside<TabItem>on the installation page): there MDX reads{#id}as an expression and the build fails, so those headings keep their generated anchor, which differs per locale; do not link to them across pages. Imports in a doc must use the@site/...alias, never a relative path, because the translated copy lives in another directory. Content files underdocs/,ai-content/andi18n/are LF (.gitattributes) so hashes and diffs agree across platforms. - Bookkeeping is
i18n/manifest.json, written byyarn i18n:mark --locale <l>: per locale and source file, the git blob SHA of the English source the translation was made from.yarn i18n:statuscompares it with the working tree (git hash-object, so it works on uncommitted edits and survives rebases and squashes) and lists new, changed, unverified, orphan and deleted pages;--stagedlooks at the index,--checkexits 1 when anything is pending,--jsonis for scripts.yarn i18n:diff --locale <l> <file>prints what changed in the English source since the translation, so a changed page is patched rather than retranslated.yarn i18n:verify --locale <l> [files]checks a translation's structure against its source (front matter keys and protected values, imports, code fences byte for byte, link targets, heading levels and ids, JSX tags, admonitions) andyarn i18n:markrecords only files that pass.yarn i18n:pruneremoves translations whose source is gone. - UI strings:
yarn i18n:stringsrunsdocusaurus write-translationsper locale (navbar, footer, sidebar categories and generated-index descriptions, blog instance titles, every<Translate>/translate()insrc/and in the AEO plugin's theme), reports keys that are still English, and drops the keys instringKeysUseDefault(footer copyright, logo alt, version label) so they keep the computed English value. Messages are translated in place ini18n/<locale>/**/*.json; keys whose English text is right for a locale (product and vendor names) go inlocales.<l>.sameAsEnglish. The command parkssrc/modules/react-animated-term/node_modulesoutsidesrc/while it runs (extractorExcludes): the extractor globs all ofsrc/and that vendored tree (36k committed files, unused) does not parse. - Pre-commit hook: .githooks/pre-commit, installed by
yarn installthrough scripts/i18n/install-hooks.js (setscore.hooksPath), runs scripts/precommit-provider-redirects.js (see "Provider catalog") and thenscripts/i18n/precommit.js. Inwarnmode (precommitin config.js, the default) it lists the staged pages whose translations will need updating; intranslatemode (orI18N_PRECOMMIT=translate) it runs the headless translator on them and stages the results into the same commit. It never blocks a commit;I18N_PRECOMMIT=offor--no-verifyskips it.yarn i18n:translate --locale <l>is the headless path: oneclaude -p "/i18n-translate <file> <locale>"per page with the subscription login Claude Code already has, then verify and mark. Each page'sokorFAILline ends with the tokens its run used (input, output, cache read, cache write, summed over the models in the CLI's JSON result) and what that would cost at API list prices (the CLI's own estimate, not a bill), followed by a subtotal per locale and a total;warnmode calls no model and reports no usage. The runs are subscription only (headless.subscriptionOnlyin config.js, on by default): bulk and incremental translation both go through this driver, which never passes an API key, starts the CLI withoutANTHROPIC_API_KEYand the other variables that outrank the stored login (in-pmode the CLI uses an API key from the environment without asking), and translates nothing unlessclaude auth statusreports a claude.ai login with no API key in play; aclaude setup-tokentoken inCLAUDE_CODE_OAUTH_TOKEN(one year, bound to the subscription) is accepted too. On this Windows machine the CLI is installed in WSL, so the driver runs it aswsl -e claude(headless.commandin config.js;-ematters, a plainwsl claudehands the tool rules to bash, which chokes on the parentheses) and the WSL install must be logged in with the subscription account (wsl -e claude auth login; its login is separate from the Windows one that VS Code uses, and it expires). The interactive path is a Claude Code session working throughyarn i18n:statuswith the same skill, fanning pages out to parallel subagents. - Chrome: the locale dropdown is a copy of theme-classic's
LocaleDropdownNavbarItemin src/theme/NavbarItem/LocaleDropdownNavbarItem showing a flag and a language code per locale (add a flag to itsflags.jsper new locale). The code is the locale's language subtag in upper case (EN, DE, ES, FR, ID, JA, KO, PT, VI, ZH), never a country code: the flag stands for a country and can change with the visitor's region, while the code names the language.codeper locale in scripts/seo-aeo/config.js is whatyarn seo:checkexpects on the switcher button and in the menu. The English flag has regional variants: a visitor in Australia, New Zealand, South Africa or the United Kingdom sees that country's flag instead of the US one. Two signals are combined, in this order: a browser language ofen-AU,en-NZoren-ZAdecides wherever the machine is; otherwise the time zone; otherwiseen-GB, which only counts when the time zone says nothing, because browsers in Australia are very often set toen-GB(that combination showed the UK flag in Melbourne while the language alone decided). The Spanish flag works the same way with Spain as the default: a visitor in one of the 19 Spanish-speaking countries of the Americas, or in Equatorial Guinea, sees that country's flag. A browser language naming one of those countries (es-MX,es-AR) decides wherever the machine is; otherwise the time zone does, whatever the language, because a browser where "Spanish" was picked reportses-ESand many are left onen-US;es-ES,es-419,es-USand bareesname no country there and keep Spain's flag. The time zone list carries every Mexican and Argentine zone by name (they share no prefix), including the pre-1993 Argentine names Chrome still reports (America/Buenos_Aires). Their emblems are reduced to a shape that reads at 20 by 15 pixels (a disc, a ring, a shield): without one Mexico reads as Italy, Ecuador as Colombia and Paraguay as the Netherlands. It is cosmetic and client-side only: src/lib/regionalFlags.js holds the mapping and builds an inline<head>script (about 2 KB, under 1 KB compressed, added throughheadTags) that sets<html data-flag-en="au">or<html data-flag-es="mx">before the first paint, andstyles.module.cssnext to the component paints the variant's artwork (an SVG data URI in that stylesheet, so nothing is fetched) over the default flag. The served HTML always carries the default flags (US, Spain), so crawlers and anything without JavaScript see no difference, and any failure (uncovered region, missing API, script error, a variant with no CSS rule) leaves the default. To add a variant: an entry inregionalFlags.js, a pair of rules instyles.module.css, and a case inflagCasesof scripts/seo-aeo/config.js (withlocalefor a locale other than English), whichyarn seo:checkruns in headless Chrome; the same section also checks that every variantregionalFlags.jscan select has artwork in the stylesheet. plugins/blog-landing prefixes its route with the locale base URL and takes the section titles from the (localized) blog instances; plugins/provider-catalog writesproviders.jsonon the default locale only. - AEO per locale:
@stackql/docusaurus-plugin-aeo>= 0.5.1 emits/<locale>/foo.md,/<locale>/llms.txtand/<locale>/llms-full.txtfrom the translated sources (older versions wrote them tobuild/<locale>/<locale>/; the published 0.5.0 did that on the live German site until the pins were bumped in November 2026), and the sitemap plugin writes/<locale>/sitemap.xml.@stackql/docusaurus-plugin-structured-data>= 1.7.1 setsinLanguageto the locale'shtmlLang, and netlify.toml has a/<locale>/* -> /<locale>/404.html 404rule per locale. - Search:
algolia.contextualSearchstaysfalseuntil the DocSearch crawler config is confirmed to record thelangfacet (with it on and no facet, every search returns nothing); with it off, results mix languages once the crawler has indexed/de/,/es/,/fr/,/id/,/ja/,/ko/,/pt-br/,/vi/and/zh-hans/. - Locale URL paths are lower case: Netlify answers a page URL that has upper-case letters with a 301 to its lower-case form (
/INSTALLING-STACKQL->/installing-stackql). The Docusaurus default path forzh-Hansis/zh-Hans/, and the first deploy (November 2026) therefore had every Chinese canonical, hreflang and sitemap URL answering with a redirect, and a broken language switcher: the page ran at/zh-hans/with a baseUrl of/zh-Hans/, theme-common strips the baseUrl from the path case-sensitively, and the English link came out as//zh-hans/, which a browser reads as a host name. The locale now setsbaseUrl: '/zh-hans/'ini18nConfig.localeConfigs(the build goes tobuild/zh-hans/); the locale code, thei18n/zh-Hans/directory,langandhreflangstayzh-Hans. docusaurus.config.js throws at load if a locale prefix has an upper-case letter, andyarn seo:check(see README, "SEO and AEO checks") checks the sitemap paths and drives the language switcher in headless Chrome. A locale whose code has upper-case letters needs the samebaseUrl:pt-BRsetsbaseUrl: '/pt-br/'from the start (build inbuild/pt-br/; the code,i18n/pt-BR/,langandhreflangstaypt-BR). - Simplified Chinese specifics: the
zh-Hanssection of i18n/glossary.md fixes the terminology (a StackQL provider is "Provider", untranslated; a cloud vendor is 云服务商), full-width punctuation in prose, and a space between Chinese and Latin text.yarn i18n:verifywarns aboutlength ratioon most Chinese pages (Chinese is shorter); that warning is expected. Verify does not catch emphasis that fails to close: in CommonMark a closing**that follows full-width punctuation and is followed directly by a Chinese character stays literal, so punctuation goes outside the markers (**适用场景**:) or a space follows them. After a Chinese pass, compare the count of bold, italic, link and inline-code nodes per page with the English source (parse both withmdast-util-from-markdown, which is innode_modules). Link text that is another page's title must be that page's translatedtitle. - French specifics: the
frsection of i18n/glossary.md fixes the terminology (a StackQL provider is "provider", untranslated and lower case; a cloud vendor is "fournisseur cloud"; a CLI flag is "option") and the typography: one ordinary space before:,;,?and!, straight quotes and apostrophes, no guillemets and no non-breaking space characters, so the sources stay greppable. Two things break a French page thatyarn i18n:verifydoes not report, because it reads front matter line by line and never parses it as YAML: a front matter value containing:(the French colon) must be in double quotes, and a single-quoted value or JSX string prop cannot hold an apostrophe. A trial build of the locale (docusaurus build --locale fr --out-dir <tmp>) catches both. - Spanish specifics: the
essection of i18n/glossary.md fixes the terminology (a StackQL provider is "provider", untranslated and lower case; a cloud vendor is "proveedor de nube"; a CLI flag is "opción"; a query is "consulta" and a statement "instrucción") and the register: neutral international Spanish for readers in Spain and Latin America alike (archivo, equipo, encabezado; never fichero, ordenador or computadora), usted,¿...?and¡...!, no space before:, straight quotes, no raya. Translators strip the trailing spaces that pad the ASCII result tables inside some code fences;yarn i18n:verifyaccepts that (it renders the same) but then reports a lowlength ratioon short pages such asjson_each.md. - Japanese specifics: the
jasection of i18n/glossary.md fixes the terminology (a StackQL provider is プロバイダー; a cloud vendor is クラウドベンダー; a statement is 文, as inSELECT文; a query is クエリ), the register (です・ます in every prose sentence, noun phrases or the dictionary form in headings, titles, table headers and list fragments, no あなた) and the typography: the long-vowel convention of current vendor documentation (サーバー, プロバイダー, パラメーター, but クエリ, リポジトリ, レジストリ), full-width 、。():「」 in prose, a half-width space between Japanese and Latin text, digits or inline code, and no nested full-width parentheses. The CommonMark emphasis trap described under Simplified Chinese applies to Japanese too, andyarn i18n:verifydoes not catch it; the first pass was checked with a scratch script comparing strong, emphasis, link and inline-code counts per page with the English source. Japanese is shorter than English, so alength ratiowarning is expected. The homepage tagline stays in English. Inyarn seo:check,jais acjklocale (kana count as Japanese text alongside Han characters); the warning about hosts that mainland China reaches poorly is forzh-Hansonly (mainlandChinain scripts/seo-aeo/config.js). - Korean specifics: the
kosection of i18n/glossary.md fixes the terminology (a StackQL provider is 프로바이더; a cloud vendor is 클라우드 제공업체; a statement is 문, as inSELECT문; a query is 쿼리; an object is 객체; built-in is 기본 제공, while embedded is 임베디드 or 내장하다), the register (합니다체 in every prose sentence, 〜하세요 for instructions and "see X", noun phrases in headings, titles, table headers and list fragments, no 당신) and the typography: Korean uses half-width Western punctuation, so there are no full-width marks, quotes are straight, words are spaced normally, and a particle attaches to the preceding word, code span or link and is chosen by the Korean pronunciation of a Latin word (StackQL은, AWS는). After inline code a noun carries the particle (SELECT문은), and after a bare URL used as link text the noun 문서 does. Two CommonMark traps thatyarn i18n:verifydoes not catch: a closing**that follows punctuation or the backtick of inline code and is directly followed by a Hangul particle stays literal, and a closing__or_directly followed by Hangul never closes, whatever precedes it (where a particle follows, the source's__bold__becomes**bold**). The first pass (November 2026) was checked with a scratch script comparing strong, emphasis, link and inline-code counts per page with the English source and link text with the target page's translated title or heading. Korean is shorter than English, so alength ratiowarning is expected. The homepage tagline stays in English. Inyarn seo:check,kois acjklocale (cjkCountin scripts/seo-aeo/lib.js counts Hangul alongside Han and kana). - Brazilian Portuguese specifics: the
pt-BRsection of i18n/glossary.md fixes the terminology (a StackQL provider is "provider", untranslated and lower case; a cloud vendor is "provedor de nuvem"; a statement is "instrução" and a query "consulta"; a CLI flag is "opção") and keeps three English words that would otherwise collide with StackQL vocabulary: a feature is "funcionalidade" because "recurso" is a resource, a template is "template" because "modelo" is an AI model, and a role is "role" because "função" is a function. The register is Brazilian only (arquivo, usuário, tela, equipe, gerenciar, baixar; the "Not" column rejects the European Portuguese ficheiro, utilizador, ecrã, equipa, gerir, descarregar), você with the imperative, task headings in the infinitive, and product names with the article Portuguese grammar asks for (o StackQL, do StackQL, a AWS). Punctuation and front matter follow the Spanish rules: no space before:, straight quotes, a value containing:in double quotes. The locale code has an upper-case letter, so it is served at/pt-br/from the start (see "Locale URL paths are lower case"). The dropdown shows the Brazilian flag (green field, yellow rhombus, blue globe and the white band, drawn as a path so noclipPathid repeats; the stars and the motto are below a pixel at 20 by 15) and the code PT, with no regional variants. Portuguese is longer than English, so alength ratiowarning fromyarn i18n:verifypoints at an omission. The homepage tagline stays in English. - Indonesian specifics: the
idsection of i18n/glossary.md fixes the terminology (a StackQL provider is "provider", untranslated and lower case; a cloud vendor is "penyedia cloud"; a resource is "sumber daya"; a query is "kueri" and a statement "pernyataan"; a CLI flag is "flag"; an MCP tool is "alat"; built-in is "bawaan" and embedded "tersemat") and the register: formal standard Indonesian in KBBI and EYD spelling, Anda with a capital A, the plain imperative for instructions, task headings with the meN- verb ("Menginstal StackQL"). The "Not" column rejects Malaysian Malay forms (fail, kemas kini, muat turun, pangkalan data, pelayan) and colloquial ones (kamu, nggak, aja, bikin). Indonesian does not inflect for number, so an English loanword never takes -s: the navbar and footer say "Provider", and the page title "Available Providers" is "Provider yang tersedia". Two slipsyarn i18n:verifydoes not catch: the prepositiondiis written apart ("di server") and the passive prefixdi-attached ("dijalankan"), and EYD's habit of italicizing foreign words must not be applied (added italics change the emphasis count the post-pass check compares). An affix on an unabsorbed English word takes a hyphen ("men-deploy", "di-deploy"), but never on inline code or a link. The locale code is lower case, so it is served at/id/with nobaseUrl. The dropdown shows the Indonesian flag (red over white) and the code ID, with no regional variants. Docusaurus ships Indonesian theme strings, but about 35 of them (the DocSearch Ask AI screen, the draft banner, the mobile dropdown labels) are still English in that pack and are translated ini18n/id/code.json; the DocSearchenterKeyHintvalues (search,enter) stay as they are, they are HTML attribute values. The same pack gives its five plural strings two forms (Satu pos|{count} pos) where Indonesian has one, and the build warns once per page about it (about 1,500 lines);code.jsonsets them to the single{count}form. The homepage tagline stays in English. - Vietnamese specifics: the
visection of i18n/glossary.md fixes the terminology (a StackQL provider is "provider", untranslated and lower case; a cloud vendor is "nhà cung cấp đám mây"; a resource is "tài nguyên"; a query is "truy vấn" and a statement "câu lệnh", while a CLI command is "lệnh"; a CLI flag is "cờ"; an MCP tool is "công cụ" and a client "ứng dụng khách"; validate is "kiểm tra tính hợp lệ" because "xác thực" is authentication, and implement is "hiện thực" because "triển khai" is deploy; install is "cài đặt" and settings "thiết lập") and keeps "template" in English because "mẫu" is a regex pattern. The register is standard written Vietnamese as in Microsoft and Google documentation: "bạn" for the reader, the plain imperative for instructions ("hãy" sparingly, never "vui lòng"), task headings as verb phrases ("Cài đặt StackQL"). Three thingsyarn i18n:verifydoes not check: every file must be Unicode NFC (Vietnamese from some input methods arrives decomposed, which renders the same but defeats grep and the glossary checks); the tone mark onoa,oeanduyis placed the traditional way (hóa, khóa, xóa, tùy, thủy, as in vendor documentation and in Docusaurus's own Vietnamese theme strings), never hoá, khoá, tuỳ, thuỷ (quýandquỹare correct either way,qubeing one consonant); andi/yfollow the dictionary forms (kỹ thuật, quản lý, quy tắc, never kĩ, quản lí, qui tắc). The first pass (November 2026) was checked with a scratch script for all three, plus mdast node counts, YAML front matter and link text against the target page's translated title or heading. Vietnamese does not inflect for number, so a loanword never takes -s: the navbar says "Provider". The locale code is lower case, so it is served at/vi/with nobaseUrl. The dropdown shows the Vietnamese flag (a yellow star on red, its points on a circle whose radius is a fifth of the flag's length) and the code VI, with no regional variants. Docusaurus ships Vietnamese theme strings with a single plural form (no plural warnings), but about 35 newer ones (the DocSearch Ask AI screen, the mobile dropdown labels, the system colour mode label) are still English in that pack and are translated ini18n/vi/code.json; the DocSearchenterKeyHintvalues stay as they are. Vietnamese is longer than English in characters, so alength ratiowarning points at an omission. The homepage tagline stays in English. - Adding a locale: add it to
i18nConfig(label,htmlLang) and toscripts/i18n/config.js(locales.<l>.sources), a glossary section, a flag, the robots sitemap line and the Netlify entries (the 404 rule and the twollms.txtheader rules); what the locale'sllms.txtand companions cover needs no configuration, it followssources; runyarn i18n:strings --locale <l>and translate the string files; run the full content pass (a session with subagents, oryarn i18n:translate --locale <l> --all);yarn i18n:verifyandyarn i18n:mark; build, serve and runyarn seo:check(add the locale to scripts/seo-aeo/config.js first), then run it again with--target prodonce deployed. Enable a locale ini18nConfigonly once its full pass is done.
Two custom plugins published to npm and one secondary content-docs instance handle the AEO pipeline. Both plugins are in sibling repos and developed alongside this site.
Source: ../docusaurus-plugin-structured-data/ (sibling to this repo)
Published: npm registry, current version pinned in package.json
Lifecycle: postBuild + allContentLoaded
Emits JSON-LD <script type="application/ld+json"> blocks into the <head> of every emitted HTML page. The shape:
WebPage+BreadcrumbList+WebSite+Organizationon every pageArticle+ImageObject+Personon blog posts (/blog/<section>/<slug>). Breadcrumbs follow the blog instance base path (Home > Blog > Section > Post) andArticle.articleSectionis['Blog', '<Section>']- needs plugin >= 1.6.0TechArticleon every doc page of the default andaidocs instances (techArticleDocsInstances: ['default', 'ai'], plugin >= 1.6.0), except the instance roots/and/ai, which stayWebPage.techArticleRoutePrefixes: ['/ai/']is kept so older plugin versions still mark/ai/*.FAQPage,HowTo,SoftwareApplicationopt-in via frontmatter (faq:,howTo:,softwareApplication:). The homepage setssoftwareApplication: true, which emits aSoftwareApplicationfrom the site defaults inthemeConfig.structuredData.softwareApplication(name,DeveloperApplication, OS, MIT license URL, download URL, freeOffer).SoftwareSourceCode(plugin >= 1.7.0) in every page's graph fromthemeConfig.structuredData.softwareSourceCode(repository, Go, MIT, platforms), referenced fromWebSite.about.- Dates (plugin >= 1.7.0):
dateModifiedis the doc's git last-update time (showLastUpdateTime: trueon the docs plugin) or the blog post's date; the build time only for pages with no date of their own (generated category indexes, React pages).datePublishedis the post date for blog posts andwebpage.datePublished(2021-07-01) for the rest. SpeakableSpecificationon every WebPage with default selectors- Connected
@graphviamainEntitylinking (TechArticle.mainEntity -> FAQPage when both present)
Config lives at themeConfig.structuredData in docusaurus.config.js. Key settings:
techArticleDocsInstancesandtechArticleRoutePrefixes- which pages get TechArticle (see above)excludedRoutes: []- nothing is excluded (exact routes or globs are accepted);/providersused to be a custom React grid and is a doc page todayauthors:- blog author identity graphorganization:- StackQL Studios identity, contact point (contactType: 'customer support', email, telephone,url: /contact-us; the plugin warns at build time ifcontactTypeis missing), address (postcode 3000, the same as src/data/contact-us/index.js), and a square 512px logo (Google wants a logo mark, not a cover image)softwareSourceCode:andsoftwareApplication:- the product blocks described above. The plugin takes no plugin options; everything is underthemeConfig.structuredData, and an option in thepluginsarray fails the build.breadcrumbLabelMap:- friendly names for breadcrumb segments. Keys are single segments ('quick-starts') or full paths ('/blog/providers'), and a full path wins. Ancestor segments only become linked crumbs when a page exists at that path; otherwise they fold into the leaf name.
If a page has no <meta name="description">, the plugin falls back to siteConfig.tagline. The homepage explicitly sets a description meta in docusaurus.config.js themeConfig.metadata to avoid the fallback on the most-cited page.
Source: ../docusaurus-plugin-aeo/ (sibling to this repo)
Published: npm registry, current version pinned in package.json
Lifecycle: postBuild + allContentLoaded + theme component injection
Four features:
.mdcompanion files - for every doc and blog page, emits a sibling.mdat the same path (e.g./foo->/foo.md,/->/index.md). Since plugin 0.5.0 the file is plain markdown rendered from the MDX source (imports, exports, expressions and presentational JSX removed;<Tabs>become bold labels; download-link components become links; everything else unwrapped and dedented), with# title,> descriptionandSource: <page URL>at the top. Only emits when there is a source markdown file (React pages and auto-generated index routes are correctly skipped - they have no source to mirror). Every page that has a companion carries<link rel="alternate" type="text/markdown" href="...">in its head, inserted inpostBuild. Note that docs/providers.md is entirely JSX rendered from the catalog, so its companion is title, description and Source only.llms.txt+llms-full.txt- at site root.llms.txtis the corpus index (Markdown bullet list with title and description per page, absolute links) and ends with an## Optionalsection linkingllms-full.txt.llms-full.txtis the concatenated companions of the AI Reference and Documentation instances only (llmsTxt.fullTxt.include), separated by\n\n---\n\n; agents read a bounded prefix of it, so the blog posts stay inllms.txtbut out of the full text.- "Ask AI" dropdown - swizzled into the breadcrumb row of every doc page and the header of every blog post, and rendered only on pages that have a companion (generated category index pages have none). The prompt links the companion by the same rule the file is written (
{companionUrl}). MUI outlined Button + Menu. Three providers: Claude, ChatGPT, Perplexity (Gemini was removed - it does not accept URL-encoded prompts). Brand icons are hand-rolled inline SVGs insrc/theme/AskAiButton/brand-icons/to avoid React-version conflicts with icon libraries. /ai/*helpers - exported from@stackql/docusaurus-plugin-aeo/helpers. Used to integrate the/ai/*content surface with the structured-data plugin.
Config lives at the plugin options object in the plugins array in docusaurus.config.js:
llmsTxt.instanceSections- section titles + ordering for thellms.txtindex (AI Reference -> Documentation -> one "Blog -" section per blog instance, generated from blogSections)askAi.providerOrder- dropdown ordering (defaults to claude, chatgpt, perplexity)askAi.promptTemplate- the prefilled prompt sent to the AI surface. Default is self-contained ("Read {companionUrl} and help me understand it. Summarize the key points, then ask me one clarifying question to dig deeper."). The user can edit it before submitting.llmsTxt.fullTxt.include- the content instances concatenated intollms-full.txt(AI Reference and Documentation).
A second @docusaurus/plugin-content-docs instance with id: 'ai', routeBasePath: '/ai', path: 'ai-content', and sidebarPath: false. Configured in docusaurus.config.js.
Directory structure under ai-content/:
ai-content/
├── index.md # /ai landing
├── canonical-definitions/ # "What is X?" pages
├── comparisons/ # "StackQL vs Y" pages
├── how-tos/ # task guides
├── concepts/ # design rationale + best practices
├── faqs/ # topic-grouped Q&A
├── architecture/ # internals
├── troubleshooting/ # error -> resolution
├── industry-positioning/ # where StackQL fits
├── tutorials/ # end-to-end walkthroughs
└── providers/ # auto-generated per-provider reference (placeholder)
Each section has an index.md landing. Individual reference pages go directly inside each section dir.
sidebarPath: false is what keeps these out of the human nav. They're reachable via direct URL, the sitemap, and llms.txt.
The preset blog is disabled (blog: false). Three @docusaurus/plugin-content-blog instances are generated from the blogSections array near the top of docusaurus.config.js (GitHub issue #288). A tag-based split was ruled out because the blog sidebar is built per instance and cannot be filtered by tag.
| Instance id | Content dir | Routes | Nav label |
|---|---|---|---|
product |
blog/product/ |
/blog/product/* |
Product Announcements |
providers |
blog/providers/ |
/blog/providers/* |
Provider Announcements |
tutorials |
blog/tutorials/ |
/blog/tutorials/* |
Tutorials |
- Each instance has its own list page, sidebar (
blogSidebarCount: 'ALL'), tags, pagination and feeds (/blog/<id>/rss.xml,atom.xml,feed.json). blog/authors.yml is shared by all three viaauthorsMapPath: '../authors.yml'. - New posts go straight into the section directory. The directory is the type - there is no marker tag. Slugs are set in front matter as before and must be unique across all three sections (the redirect generator checks this).
/blogis a landing page built by the local plugin plugins/blog-landing/index.js. It reads the three instances inallContentLoaded(the only hook that sees other plugins' content) and adds a route rendering src/components/BlogLanding/index.jsx with the newest five posts per section.- Every pre-split post URL (
/blog/<slug>and its.mdcompanion) has a 301 to its new home in netlify.toml. The per-post block between theBEGIN/END generated blog redirectsmarkers is owned by scripts/generate-blog-redirects.js, which derives rules from front matter slugs. Rerun it only if a pre-split post's slug or section changes; posts written after the split never had an old URL and need no rule, so add each new post's slug toPOST_SPLIT_SLUGSin the script. Old/blog/tags/*,/blog/page/*,/blog/archiveand/blog/authorsgo to/blog; the old feed URLs go to the product announcements feeds. - A post file must live inside a section directory. A file at
blog/root belongs to no instance, is silently not built, and gets no redirect (one tutorial sat there for two weeks after the split and its old URL 404'd). - The navbar "More" dropdown and the footer list the three sections plus Quick Starts; both are derived from
blogSections. The two announcement entries carry a bullhorn (navLabel) in the header only. The/bloglanding page is deliberately not linked from the header or footer; it is reachable by URL and from the sitemap. - "Tutorials" in the nav means the blog section. The docs walkthroughs formerly at
/docs/tutorials/*are "Quick Starts" at/quick-starts/*(directorydocs/quick-starts/, sidebar category in sidebars.js). Old URLs are 301'd in netlify.toml, including/tutorials->/blog/tutorialsand/cookbooks->/quick-starts(both were meta-refresh React stubs, now deleted). - Sitemap:
lastmod: 'date'per URL from the source file's last git commit (changefreqandpriorityare off; crawlers ignore them).ignorePatternscover/blog/*/tags/**,/blog/*/page/**,/blog/*/archiveand/blog/*/authors(list pages, not content). Those same pages (about 300 tag pages and 20 paginated list pages across the three instances) are also markednoindex, followby the wrappers in src/theme/BlogTagsPostsPage, src/theme/BlogTagsListPage and src/theme/BlogListPage (page 2 onwards only; page 1 is the section landing), via src/theme/NoIndex. They are linked from every post, so Google crawls them regardless of the sitemap; the noindex stops them piling up under "Crawled - currently not indexed". - The
breadcrumbLabelMapentries for the section ids are generated fromblogSections, so JSON-LD breadcrumbs read "Product Announcements" rather than "product". - The shared nav used by the provider microsites lives in
../docusaurus-config(vendored by those sites at build time). Its Blog/Tutorials links must be kept in step with the main site nav.
netlify.toml sets MIME types and cache headers for the AEO files. Critical rules:
*.md->text/markdown; charset=utf-8(top-level and nested)/llms.txtand/llms-full.txt->text/plain; charset=utf-8- All three get
X-Robots-Tag: index, followandmax-age=300cache /providers.json(the published provider catalog, see "Provider catalog" below) ->application/json; charset=utf-8, the same 5-minute cache andAccess-Control-Allow-Origin: */.well-known/openai-apps-challenge->text/plain; charset=utf-8, no cache,noindex. The file is not in the repo: when the OpenAI plugin portal asks for domain verification, save the token it shows asstatic/.well-known/openai-apps-challenge(token only, no trailing newline). Docusaurus copiesstatic/dotfiles into the build.
Without these rules Netlify serves .md as application/octet-stream (browsers download instead of display) and crawlers may skip it.
Redirect rules live in the same file and their order matters (first match wins): the query library proxy, then specific legacy /docs/... rules, then the /docs/* -> /:splat catch-all, then the hand-written top-level aliases (/tutorials, /cookbooks, /install, /downloads, /stackqldocs), then the generated provider block, then the remaining hand-written rules, then the generated per-post blog block. See "Redirects are Netlify 301s, never pages" above.
The StackQL query library lives in its own repo/site (query-library.stackql.io)
and is served under the canonical path https://stackql.io/docs/query-library/*
via a Netlify 200 proxy rewrite in netlify.toml. This repo
holds no library content, build tooling or CI - just the rewrite rule and a
navbar link to /docs/query-library/ (an href, not to, so it is a full
page load rather than a client-side route). Response headers for the proxied
path (content types, CORS, cache) come from the origin site, not this repo's
netlify.toml. The path 404s under yarn serve/yarn start - expected,
Netlify-only behaviour. Do not add files under static/docs/query-library/:
Netlify serves matching static files in preference to redirect rules, so any
file there would shadow the proxied site.
src/configs/providers.json is the single source of truth for everything provider-related on this site: config, not code. It is an array of categories, each with providers of { name, href, icon, deployedBy, repo, branch, invertOnDark?, registryAliases? }. deployedBy is the microsite's hosting platform, netlify or github (GitHub Pages); repo is the GitHub repository of the provider and its microsite as owner/name, and branch the branch the microsite is deployed from (today always the repository's default branch). None of the three is rendered on this site; they are published in /providers.json so cross-repo automation can tell where each microsite lives and how to redeploy it. The code that reads it is src/lib/providers.js, which validates it, derives each provider's slug and path and exposes PROVIDER_CATEGORIES, PROVIDERS, providerRoutes() and registryRoutes(). Nothing else in the repo holds provider lists; the former src/configs/providers-data.json, providers.ts and the unused ProviderCards component were removed. The catalog drives:
- the tiles and table of contents on docs/providers.md, which imports from
src/lib/providers. Tiles and TOC entries link straight to the microsite (href), in the same tab (customProps.target: '_self', honoured by the swizzled src/theme/DocCard), with no redirect hop. - the navbar "Providers" menu: a two-level dropdown (category -> provider, every entry, catalog order) rendered by the custom navbar item type
custom-providersDropdownin src/theme/NavbarItem/ProvidersDropdownNavbarItem/index.js and configured as the "Providers" entry in docusaurus.config.js. Category rows link to/providers#<category id>, provider rows straight to the microsite (hrefwithhtmlinstead oflabelso there is no external-link icon,target="_self",rel="noopener"so the microsite keeps the referrer). Desktop is a hover/focus flyout per category; the mobile sidebar gets nested collapsibles. - the published catalog at
/providers.json, written into the build by plugins/provider-catalog/index.js (postBuild only, so not undernpm run start). It is a cross-repo contract: the shared chrome in../docusaurus-config, vendored at build time by every provider microsite and by the query library, fetches it when those sites build and generates their own two-level Providers menu from it. The shape (version 1) is documented in the plugin. Adding a field is fine; renaming or removing one, or moving the file, breaks those builds, so bump the version and change the consumer first. Netlify serves it with CORS and a 5-minute cache. - two families of Netlify 301 rules to
https://<slug>-provider.stackql.io/, theBEGIN/END generated provider redirectsblock in netlify.toml written by scripts/generate-provider-redirects.js. They used to be Docusaurus routes rendering a meta-refresh page (plugins/provider-redirects,src/components/ProviderRedirect), which Search Console reported as "Page with redirect" for every entry; both were removed in October 2026. The block is kept in step by the pre-commit hook: when a commit touches the catalog, src/lib/providers.js, the generator ornetlify.toml, scripts/precommit-provider-redirects.js regenerates the block from the stagedproviders.json(buildCatalog()), writes it into the stagednetlify.tomland the working tree copy, and leaves any other unstaged edit tonetlify.tomlunstaged. A staged catalog that does not validate is reported and nothing changes; the hook never blocks a commit, andPROVIDER_REDIRECTS_PRECOMMIT=offskips it. Before the hook, OVH was added to the catalog without rerunning the generator, so/providers/ovhand/registry/ovhhad no rule and answered 404./providers/<slug>is explicit: exactly one rule per catalog entry, no exceptions. Nothing inside the site links here any more (tiles and navbar go straight to the microsite); it is kept for inbound links and the old sitemap./registry/<name>is the inbound surface for external links: one rule per catalog entry plus each entry'sregistryAliases, so a provider family exposes one canonical inbound link (/registry/databricks-> the Databricks Account microsite)./providersitself is the catalog doc page (docs/providers.md) now that docs live at the root; the bare/registry301s to it.
The slug is derived from href, which must be exactly https://<slug>-provider.stackql.io/; the module throws at config load on a missing field, a malformed href or a duplicate slug or alias. To add a provider, add one entry to the JSON and commit it (the hook adds the rules; node scripts/generate-provider-redirects.js does the same on the working tree). Do not create pages under src/pages/providers or src/pages/registry: a built file there would shadow the Netlify rule for that path. The retired /providers/databricks URL is a hand-written 301 straight to the Databricks Account microsite (a single hop, not via /registry/databricks).
The provider microsites and the query library get their nav from ../docusaurus-config, which builds its own Providers menu from this site's /providers.json at build time (see the bullet above), so there is no featured list to keep in step any more. A new catalog entry shows up on those sites on their next build after this site deploys.
src/components/Gist/index.jsx - local replacement for the unmaintained react-gist package (was blocking React 18 upgrade). Drop-in compatible: same <Gist id="..." /> API. Used by two blog posts.
src/theme/DocItem/Footer/index.js - copy of the theme-classic doc footer with one addition: a doc with hide_last_update: true in its front matter drops the "Last updated" row while keeping tags and the edit link. Only the homepage uses it, so search results do not show a modification date on a landing page. showLastUpdateTime stays on globally. Keep this file in step with theme-classic when Docusaurus is upgraded.
src/theme/NavbarItem/ComponentTypes.js - wraps the theme-classic navbar item registry and adds the site's custom types. One so far: custom-providersDropdown (see "Provider catalog" above). Its desktop and mobile markup copy theme-classic's DropdownNavbarItem; keep them in step when Docusaurus is upgraded.
src/theme/DocCard/index.js - copy of the theme-classic doc card with one addition: a sidebar item's customProps can replace the default emoji with iconComponent (a React node), icon (an image path under static/, with invertOnDark to invert it in dark mode) or emoji. Link items and category items both honour it. The tiles on docs/providers.md and the four Quick Starts provider categories in sidebars.js use icon; the Quick Starts entries look the icon up in the provider catalog by slug, so the cards follow src/configs/providers.json.
Every doc has its own description:; the old boilerplate ("Query and Deploy Cloud Infrastructure and Resources using SQL") was shared by 89 pages and is gone. Google uses the description as the snippet under a sitelink and treats repetition as a reason to withhold sitelinks, so a new doc needs a one-sentence description written from its content, not a copied one. The homepage title is deliberately descriptive ("SQL for cloud infrastructure, SaaS APIs and AI agents") with sidebar_label: Welcome to StackQL keeping the sidebar entry short.
The structured-data plugin reads several frontmatter fields directly. Use these on /ai/* pages especially.
---
title: What is StackQL?
description: One-sentence definition - this becomes the JSON-LD WebPage.description, the llms.txt entry's description, and the OG description.
keywords: [stackql, sql, cloud, api]
proficiencyLevel: Beginner # Beginner | Intermediate | Expert - sets TechArticle.proficiencyLevel
dependencies: stackql >= 0.6 # optional string - sets TechArticle.dependencies
faq:
- question: Is StackQL a database?
answer: No. StackQL is a query runtime...
- question: Does StackQL replace Terraform?
answer: Not directly. Terraform's primary job is...
---When faq: is present, the plugin emits a FAQPage JSON-LD node and links it to the TechArticle via mainEntity. The .md companion preserves the frontmatter verbatim, so an LLM ingesting the markdown gets the FAQ pairs as content too.
howTo: and softwareApplication: work the same way. See the structured-data plugin README for the full shapes.
- Build with the AEO env vars set:
ALGOLIA_APP_ID=dummy ALGOLIA_API_KEY=dummy ALGOLIA_INDEX_NAME=dummy npm run build(local builds only - production gets real values). - Check that the build emits expected
.mdcompanions:find build -name "*.md" -type f | wc -lshould be ~1837 across the ten locales (about 320 English, 164 German, 164 Spanish, 164 French, 164 Indonesian, 164 Japanese, 164 Korean, 164 Brazilian Portuguese, 164 Vietnamese, 208 Chinese: one per page that exists in that language).find build/de/ai build/de/blog build/es/ai build/es/blog build/fr/ai build/fr/blog build/id/ai build/id/blog build/ja/ai build/ja/blog build/ko/ai build/ko/blog build/pt-br/ai build/pt-br/blog build/vi/ai build/vi/blog build/zh-hans/blog -name "*.md" | wc -lmust be 0: an untranslated page gets no companion under a locale path. - Check that
build/llms.txtandbuild/llms-full.txtexist and are non-empty. - Check that
build/providers.jsonexists and lists every catalog category: the provider microsites and the query library build their Providers menu from it. - After editing a doc,
yarn i18n:statuslists the translations that now need updating (see "Internationalization");yarn i18n:status --checkis clean when every configured locale is current. A new doc needsyarn write-heading-ids . docs ai-contentbefore it is translated. - For
/ai/*pages, verify the JSON-LD by inspecting the rendered HTML forTechArticle+FAQPagetypes (script we wrote in earlier sessions can be reproduced if needed).
- Pick the right directory by answer intent (definition, comparison, how-to, etc.).
- Write the page in the same voice as ai-content/canonical-definitions/what-is-stackql.md - direct, declarative, technical-encyclopedia tone (think Wikipedia, not a vendor blog).
- Always include
description:in frontmatter - this drives JSON-LD, llms.txt, and OG metadata. - Use
faq:frontmatter rather than the<script type="application/json" data-aeo-faq>MDX pattern. Both work; frontmatter is cleaner. - Cross-link to related
/ai/*pages even if they don't exist yet - mark them as "not yet written" so Docusaurus'sonBrokenLinks: 'throw'doesn't fail the build. As pages are written, convert the plain-text references to real links.
- The structured-data plugin doesn't care if you change content - it re-runs on every build. But if you add
faq:,howTo:,proficiencyLevel:, ordependencies:to frontmatter, those will surface in the JSON-LD automatically.
The two AEO plugins are developed in sibling repos. To bump:
yarn add @stackql/docusaurus-plugin-structured-data@<version>
yarn add @stackql/docusaurus-plugin-aeo@<version>
If the build breaks after a bump, the plugin's CHANGELOG.md is the first place to look. Both plugins maintain detailed changelogs noting breaking changes and config migrations.
npm run start does NOT run postBuild, so:
- No
.mdcompanions are emitted - No
llms.txtis emitted - JSON-LD from the structured-data plugin is NOT injected (it runs in postBuild)
But the Ask AI button (theme component) DOES render in dev. To verify the full AEO pipeline locally, run npm run build && npm run serve instead.
After plugin changes, dev cache must be cleared: rm -rf .docusaurus && npm run start. Hard refresh the browser too (Ctrl+F5).
react-gist@1.2.4 declares react: <=17 as a peer dep. Replaced with the local src/components/Gist/index.jsx component to drop the conflict. Do not reintroduce react-gist.
When the live site changes, AI fetch tools (Claude.ai's web_fetch, ChatGPT's browse, Perplexity) may serve cached responses for some hours. If a recently-deployed .md URL appears as 404 in an LLM response, check the URL directly with curl first - if curl returns 200, the bot is using a stale cache. Wait a few hours and retest.
These routes are React pages, the blog landing plugin route, blog list pages, or generated category index pages (/getting-started, /command-line-usage, /quick-starts/*) with no source markdown. The AEO plugin correctly does not emit .md companions for them. They appear in the human nav but not in llms.txt or anywhere requiring a .md twin. This is by design - do not "fix" by trying to force .md emission. The navbar and footer link to the canonical pages (/, /installing-stackql, /providers), so crawlers see real site structure; keep it that way when adding chrome links. /install, /downloads, /stackqldocs, /stackql-deploy, /features, /tutorials, /cookbooks, /providers/<slug> and /registry/<name> are Netlify 301s, so they 404 under yarn serve. /privacy, /terms and /support are MDX pages under src/pages; the AEO plugin mirrors only the docs and blog instances, so they get no companion either (checked in the November 2026 build), and /contact-us is a React page and does not.
The Ask AI button is hidden below 997px viewport width (the Docusaurus mobile breakpoint) to keep the breadcrumb row uncluttered. To verify the button on a desktop test, the browser window must be wider than 997px.
# Local dev server (no AEO postBuild, no JSON-LD)
npm run start
# Full production build (AEO + JSON-LD + .md companions)
ALGOLIA_APP_ID=dummy ALGOLIA_API_KEY=dummy ALGOLIA_INDEX_NAME=dummy npm run build
# Serve the production build locally to verify
npm run serve
# Clear dev cache after plugin changes
rm -rf .docusaurus build
# Inspect emitted JSON-LD on a page
grep -A1 'application/ld+json' build/command-line-usage/exec.html | head -20
grep -A1 'application/ld+json' build/blog/product/stackql-mcp-server-now-available.html | head -20
# Count .md companions
find build -name "*.md" -type f | wc -l
# Check llms.txt structure
grep -E '^## ' build/llms.txt
# Regenerate the per-post blog redirect block in netlify.toml
node scripts/generate-blog-redirects.js
# Regenerate the provider redirect block in netlify.toml (the pre-commit hook does this when providers.json is committed)
node scripts/generate-provider-redirects.js
# Translations (see "Internationalization"): what needs doing, check one, record it
yarn i18n:status
yarn i18n:verify --locale de docs/installing-stackql.md
yarn i18n:mark --locale de docs/installing-stackql.md
yarn i18n:strings # refresh navbar/footer/sidebar/code strings per locale
ls build/de/*.md | wc -l; head -5 build/de/llms.txt # German companions and llms.txt after a build
grep -E '^## ' build/de/llms.txt build/es/llms.txt build/fr/llms.txt build/id/llms.txt build/ja/llms.txt build/ko/llms.txt build/pt-br/llms.txt build/vi/llms.txt build/zh-hans/llms.txt # de, es, fr, id, ja, ko, pt-BR and vi: Documentation only; zh-Hans: AI Reference and Documentation
find build/de/ai build/de/blog build/es/ai build/es/blog build/fr/ai build/fr/blog build/id/ai build/id/blog build/ja/ai build/ja/blog build/ko/ai build/ko/blog build/pt-br/ai build/pt-br/blog build/vi/ai build/vi/blog build/zh-hans/blog -name '*.md' | wc -l # expect 0 (no English copies under a locale)
# Search Console hygiene: no redirect stubs or noindex pages in the sitemap
grep -c '<loc>' build/sitemap.xml
grep -E 'stackql.io/(providers/|registry|install$|downloads$|stackqldocs$)' build/sitemap.xml # expect nothing
grep -l 'content="noindex, follow"' build/blog/*/tags/*.html | wc -l # expect every tag page../docusaurus-plugin-structured-data- JSON-LD emission plugin source. Bug fixes for stackql.io-specific issues land here first, then ship to npm.../docusaurus-plugin-aeo- AEO plugin source. Same pattern.../docusaurus-config- the shared chrome vendored at build time by the provider microsites and the query library. It fetches this site's/providers.jsonto build its Providers menu, and itstheme/NavbarItemis a copy of src/theme/NavbarItem/ProvidersDropdownNavbarItem/index.js adapted to that data source; change the two together.../../stackql-registry- StackQL provider registry. Houses the StackqlDeployDropdown component whose styling the Ask AI button was modeled on.