Conversation
Signed-off-by: Salvydas Lukosius <ss-o@users.noreply.github.com>
- Replace hardcoded ~/.zi paths with ${XDG_DATA_HOME:-$HOME/.local/share}/zi
- Update ZI[HOME_DIR]/ZI[BIN_DIR] defaults in installation and commands guides
- Update ZPFX/polaris references across plugin standard, customization,
bin-gem-node annex, syntax guide, and zi_console docs
- Replace deprecated git.io short URLs with zshell.dev equivalents
Introduces community/04_zunit/ with eight pages covering installation, test syntax, assertions, running tests, configuration, and CI integration.
Co-authored-by: ss-o <ss-o@users.noreply.github.com>
…ing section (#728) * feat(docs): add z-shell syntax highlighting * docs(community): restructure contributing section with SVG illustrations - Create community/00_contributing/ as first-priority section - index.mdx: overview with banner SVG + card grid layout - 01_getting_started.mdx: org-wide fork/branch/commit/PR guide - 02_contributing_to_zi.mdx: zi-specific contributing guide - 03_zsh_plugin_standard.mdx: moved from community root (slug preserved) - 04_contributing_docs.mdx: wiki MDX authoring and Crowdin guide - 05_project_management.mdx: absorbs project tracker + labels content - Add six SVG illustrations to static/img/svg/community/: - contributing-banner.svg: wide workflow diagram (fork→code→PR→merge) - contributing-getting-started.svg: git branch tree (120×120) - contributing-zi.svg: gear with zi logo (120×120) - contributing-plugin-standard.svg: plug/socket icon (120×120) - contributing-docs.svg: document with pen (120×120) - contributing-project-management.svg: kanban board (120×120) - Renumber community top-level: - 02_zsh_plugin_standard.mdx removed (moved into 00_contributing/) - 03_zsh_native_scripting_handbook.mdx → 02_ - 04_zunit/ → 03_zunit/ (update _category_.json position + doc link) - Fix ZUnit broken links in index.mdx, 01_installation.mdx, 04_running-tests.mdx by adding .mdx extension (forces correct file-based resolution) - Update community/index.mdx with contributing CTA section Closes: docs/project-tracker-and-labels branch (content absorbed) * feat(highlight): unified zsh/zi/zunit prism grammar with token colors - Expand zsh grammar: adds zsh-builtin (30+ builtins), zsh-expansion-flag, zsh-special-parameter, zsh-glob-qualifier alongside existing zi/zunit tokens - Simplify prism-include-languages.ts to swizzle delegation pattern - Add comprehensive CSS token palette (9 token types, light + dark themes) - Fix dead link in zsh_startify.mdx (z-shell/zsh-startify repo is gone) - Migrate 44 MDX files from shell to zsh/zi/zunit language fences * fix(docs): remove dead links to non-existent GitHub repositories - ecosystem/plugins/zsh_startify.mdx: remove link to z-shell/zsh-startify (404) and remove FontAwesome icon from heading (FA kit removed from wiki) - community/gallery/collection/06_plugins.mdx: remove hyperlink from zsh-startify heading (repo no longer exists) - community/00_contributing/index.mdx: fix broken CODE_OF_CONDUCT link (z-shell/zi repo has no CODE_OF_CONDUCT.md) — use contributor-covenant.org - community/00_contributing/02_contributing_to_zi.mdx: fix same broken CODE_OF_CONDUCT link; remove link to z-shell/community guidelines (repo 404) * feat(highlight): implement zsh/zi/zunit prism grammar and token CSS - z-shell-languages.ts: rewrite grammar using named capture groups for ESLint prefer-named-capture-group compliance; expand zsh-builtin list to 50+ builtins; rename zsh-keyword → zsh-builtin; add zsh-expansion-flag token; reorganize insertBefore calls for correct priority ordering - prism-include-languages.ts: replace manual additionalLanguages loop with clean swizzle delegation to @theme-original/prism-include-languages - custom.css: add 9-token semantic color palette (light + dark) for zsh-builtin, zsh-expansion-flag, zsh-special-parameter, zsh-glob-qualifier, zi-command keyword, zi-command subcommand function, zi-ice, zunit-command, zunit-directive, zunit-assertion; uses CSS custom properties and nested rules * fix(docs): fix admonition titles and lychee exclusion - Convert space-separated admonition titles to bracket syntax (MDX v3 requirement): :::note Title -> :::note[Title] in 4 files - Add z-shell/zsh-startify to lychee exclude list — repo is archived/removed and is referenced in existing docs on the target (next) branch; Trunk checks both PR and base versions, causing false CI failures * fix(ci): correct build-script for compressed-size-action The action prepends 'pnpm run' to the build-script value, so passing 'pnpm build:en' ran 'pnpm run pnpm build:en' — a non-existent script. Change to the bare script name 'build:en' so the action runs 'pnpm run build:en' correctly. * fix(highlight): correct CSS selector and override inline Prism theme colors prism-react-renderer applies inline style="color:..." to token spans using the Dracula/GitHub theme's alias colors, which beats plain CSS rules. Two fixes: - Selector: token colors were targeting <code> but Docusaurus puts language-* on <pre>; change to pre.language-* selectors. - Override: add !important to all custom token color declarations so they win over the inline styles. Also migrate z-shell/community membership links to z-shell/.github (community repo is private; .github has the same 05_membership.yml template and public issues enabled). * fix(highlight): flatten CSS selectors — Docusaurus pipeline strips CSS nesting Nested rules inside :is() and block selectors were mangled by the build, producing invalid CSS like `.language-zsh,...) .token.zsh-builtin` with the `pre` and `:is(` prefix stripped. Flattened all token color rules to standard descendant selectors which the pipeline processes correctly. * fix(highlight): expand zi/zunit grammar coverage zi-command: add light-mode, self-update, cdreplay, cdlist, status zi-ice: add compile, eval, extract, has, if, nocd, sbin, svn (all appear in ecosystem/docs pages but were tokenized as plain text) zunit-command: broaden pattern from strict lookahead to match bare zunit and any subcommand/flag, using lookbehind for boundary * feat(docs): redesign four landing pages with banner SVGs and card grids Each page now matches the contributing page pattern: - Full-width 720×140 banner SVG illustrating the section topic - :::info/:::tip admonition with key links or quick facts - CSS grid of cards (icon + title + description + arrow link) Pages updated: docs/, ecosystem/, community/, community/zunit/ SVGs created: docs-banner, ecosystem-banner, community-banner, zunit-banner All card links verified against actual built URLs. * fix(highlight): fix zi-command compound selector and zi-ice token priority prism-react-renderer v2 renders `inside` tokens as compound classes on the same span, not nested spans — fix CSS to use .token.zi-command.keyword instead of descendant .token.zi-command .token.keyword. Move zi-ice insertBefore to fire before zsh-builtin so ice modifiers like 'wait' and 'src' are not mis-tokenized as shell builtins in zi blocks. Also redesign docs/ecosystem/community/zunit banner SVGs with distinct color palettes (blue/amber/purple/teal-red) so each section has a unique visual identity. * fix(docs): remove zsh-startify — plugin not under z-shell org Remove ecosystem/plugins/zsh_startify.mdx (was draft: true) and the corresponding gallery entry in 06_plugins.mdx. The plugin is hosted under a third-party org that we do not reference in Z-Shell docs. --------- Co-authored-by: ss-o <ss-o@users.noreply.github.com>
Re-pinned every action (workflows + .trunk/setup-ci) to verified release SHAs; fixes Trunk Check + CodeQL failing at job setup. Closes #738.
…oundaries (#736) Reconciles the divergent docs/maintainers vs community/maintainers duplicate (kept canonical SB_SECRET_KEY copy), moves it to community/10_maintainers/, and hardens AGENTS.md + authoring instructions so docs/ stays Zi-user-docs-only.
# Conflicts: # AGENTS.md # community/00_contributing/02_contributing_to_zi.mdx # community/03_zunit/01_installation.mdx # community/03_zunit/06_ci.mdx
…nfig - query.mjs: parse response as text first; surface HTTP status + body on non-JSON errors instead of crashing - index.ts: wrap the Edge Function handler in try/catch returning internal_error - migration: schema-qualify vector distance as OPERATOR(extensions.<=>) so match_public_docs works under 'set search_path = ''' - add supabase/config.toml (local CLI config) and supabase/.gitignore
- functions/[[path]].ts: implement Range + If-None-Match handling (206/304) so the advertised preflight headers are actually supported; add Accept-Ranges - prism: use plain capturing groups instead of named groups for Prism lookbehind (older-browser regex compatibility) - embed-docs: skip re-embedding sources whose content_hash is unchanged, and batch embeddings into one request per document instead of one per chunk
The Supabase Knowledge Search maintainer guide is operational documentation (secret names, infra topology, ops CLIs) and does not belong on the public wiki. Relocated to z-shell/.github/runbooks/supabase-knowledge-search.md. Updates the content-root boundaries: community/ holds community content only; maintainer / operational runbooks live in z-shell/.github/runbooks/. Refs ADR 0006.
The lockfile auto-merge left a dangling ws@8.20.0 reference (main bumped ws to 8.20.1), breaking 'pnpm i --frozen-lockfile' in CI. Re-resolved the lockfile.
…sponses Addresses CodeQL 'information exposure through a stack trace': log error details server-side and return only a generic error code to the client.
Reverts the plain-capture-group change: the repo's eslint config enforces prefer-named-capture-group, and Prism's lookbehind:true requires a capturing (not non-capturing) group, so named groups are the only option that satisfies both. Named capture groups are ES2018 and supported across the project's browserslist targets.
Member
Author
|
@copilot resolve the merge conflicts in this pull request |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces a Supabase-backed “knowledge search” pipeline (vector store schema + indexing/query tooling + CI workflow) while also updating multiple docs/pages references and cleaning up repository guidance by removing the .github/codebase/* knowledge docs in favor of consolidated instruction/guideline sources.
Changes:
- Add documentation semantic-search infrastructure: Supabase migration + Edge Function, Node indexer/query scripts, and a GitHub Actions workflow to re-index on docs changes.
- Update and expand project/documentation authoring guidance (content-root selection) and refresh multiple docs links (e.g.,
zdharma/*→z-shell/*/ pinned snippet URLs). - Pin multiple GitHub Actions to specific commit SHAs and remove several
.github/codebase/*markdown “codebase scan” documents.
Reviewed changes
Copilot reviewed 39 out of 41 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| supabase/migrations/20260521000000_create_docs_search.sql | Creates docs_search schema/tables, vector index, and a public RPC for semantic search. |
| supabase/functions/knowledge-search/index.ts | Adds Supabase Edge Function to embed queries via OpenAI and call the RPC. |
| supabase/config.toml | Adds Supabase CLI local config, including Edge Function config. |
| supabase/.gitignore | Ignores Supabase local working dirs and dotenvx artifacts. |
| scripts/knowledge-search/collect-docs.mjs | Collects/chunks MD(X) docs for indexing. |
| scripts/knowledge-search/collect-docs.test.mjs | Adds unit tests for doc collection/chunking helpers. |
| scripts/knowledge-search/embed-docs.mjs | Indexes docs into Supabase (sources + chunks + embeddings) and records ingestion runs. |
| scripts/knowledge-search/embed-docs.test.mjs | Adds unit tests for env validation + hashing. |
| scripts/knowledge-search/query.mjs | CLI helper to call the Edge Function and print results. |
| scripts/knowledge-search/query.test.mjs | Adds unit tests for env validation + formatting output. |
| package.json | Adds knowledge-search scripts and new npm dependencies. |
| pnpm-lock.yaml | Locks openai and postgres dependency additions. |
| .github/workflows/knowledge-search-index.yml | Adds workflow to run the indexer on main when docs/scripts change. |
| functions/[[path]].ts | Adds a catch-all Cloudflare Pages Function to serve missing paths from R2. |
| functions/tsconfig.json | Adds TS config for Cloudflare Pages Functions type-checking. |
| .gitignore | Ignores Wrangler-generated functions/worker-env.d.ts. |
| .trunk/setup-ci/action.yml | Pins actions/setup-node by commit SHA. |
| .github/workflows/trunk-check.yml | Pins actions and normalizes workflow naming. |
| .github/workflows/r2-sync.yml | Pins actions and normalizes workflow naming. |
| .github/workflows/pages-deployment.yml | Pins actions and normalizes workflow naming. |
| .github/workflows/crowdin-upload.yml | Pins actions and normalizes workflow naming. |
| .github/workflows/crowdin-download.yml | Pins actions and normalizes workflow naming. |
| .github/workflows/codeql.yml | Pins checkout and codeql-action by commit SHA. |
| .github/workflows/ci-perf.yml | Pins actions by commit SHA and normalizes workflow naming. |
| .github/instructions/docs-authoring.instructions.md | Adds explicit content-root selection rules (incl. runbooks prohibition). |
| .github/instructions/agent-docusaurus-writer.instructions.md | Adds guidance for choosing the correct content root. |
| AGENTS.md | Clarifies content-root boundaries and links to org-wide guidelines/runbooks. |
| ecosystem/plugins/zsh_lint.mdx | Adds a new plugin page. |
| ecosystem/annexes/2_meta_plugins.mdx | Updates repository links (e.g., zdharma/* → z-shell/* / pinned snippet URLs). |
| docs/getting_started/01_installation.mdx | Updates ZUnit link to z-shell/zunit. |
| community/gallery/collection/03_programs.mdx | Updates revolver/zunit references and link targets. |
| community/03_zunit/06_ci.mdx | Updates CI snippet download URLs to pinned z-shell/src locations. |
| community/03_zunit/01_installation.mdx | Updates Revolver/Color download URLs + legacy naming references. |
| community/00_contributing/02_contributing_to_zi.mdx | Updates repo naming references (zi-src → src). |
| .github/codebase/ARCHITECTURE.md | Removed codebase-scan knowledge doc. |
| .github/codebase/CONCERNS.md | Removed codebase-scan knowledge doc. |
| .github/codebase/CONVENTIONS.md | Removed codebase-scan knowledge doc. |
| .github/codebase/INTEGRATIONS.md | Removed codebase-scan knowledge doc. |
| .github/codebase/STACK.md | Removed codebase-scan knowledge doc. |
| .github/codebase/STRUCTURE.md | Removed codebase-scan knowledge doc. |
| .github/codebase/TESTING.md | Removed codebase-scan knowledge doc. |
Files not reviewed (1)
- pnpm-lock.yaml: Language not supported
Comments suppressed due to low confidence (1)
package.json:63
openaiandpostgresare only used by the Node-based indexing/query scripts underscripts/knowledge-search/, not by the Docusaurus site runtime. Consider moving them fromdependenciestodevDependenciesto avoid inflating the production install set and to better reflect their tooling-only usage.
"dependencies": {
"@docusaurus/core": "3.10.1",
"@docusaurus/faster": "3.10.1",
"@docusaurus/plugin-ideal-image": "3.10.1",
"@docusaurus/plugin-pwa": "3.10.1",
"@docusaurus/preset-classic": "3.10.1",
"@mdx-js/react": "3.1.1",
"asciinema-player": "3.15.1",
"clsx": "2.1.1",
"openai": "^6.38.0",
"postgres": "^3.4.9",
"prism-react-renderer": "2.4.1",
"prismjs": "1.30.0",
"react": "^19.2.5",
"react-dom": "^19.2.5"
},
Comment on lines
1
to
5
| # Project Guidelines | ||
|
|
||
| This project follows the organization-wide [Z-Shell Organization Guidelines](https://github.com/z-shell/.github/blob/main/AGENTS.md). | ||
|
|
||
| ## Build, Lint, and Dev Commands |
| { | ||
| "compilerOptions": { | ||
| "target": "ES2022", | ||
| "lib": ["ES2022"], |
Comment on lines
+29
to
+55
| const url = new URL(context.request.url); | ||
| const key = url.pathname.slice(1); | ||
|
|
||
| if (!key) { | ||
| return response; | ||
| } | ||
|
|
||
| // Honor the conditional (If-None-Match) and Range request headers advertised | ||
| // in the OPTIONS preflight by forwarding them to R2. | ||
| const object = await context.env.ASSETS_BUCKET.get(key, { | ||
| onlyIf: context.request.headers, | ||
| range: context.request.headers, | ||
| }); | ||
|
|
||
| if (!object) { | ||
| return response; | ||
| } | ||
|
|
||
| const headers = new Headers(); | ||
| object.writeHttpMetadata(headers); | ||
| headers.set("Cache-Control", "public, max-age=31536000, immutable"); | ||
| headers.set("ETag", object.httpEtag); | ||
| headers.set("Access-Control-Allow-Origin", "*"); | ||
| headers.set("Accept-Ranges", "bytes"); | ||
| if (url.pathname.startsWith("/cdn/")) { | ||
| headers.set("X-Robots-Tag", "noindex, noarchive"); | ||
| } |
|
|
||
| Clone the repository and source the plugin: | ||
|
|
||
| ```shell title="~/.zshrc" |
Contributor
Resolved the conflict locally by applying the |
Wrangler 4 dropped Node 20 support, which broke the Deploy Wiki and r2-sync workflows. Bump setup-node to 22 across the wrangler and CI workflows.
The Supabase-backed semantic search had no live frontend consumer (site search is Algolia DocSearch; SearchBar.tsx only tweaks aria attributes), and its indexer workflow was failing on main. Remove the supabase/ project, scripts/knowledge-search/, the indexer workflow, the openai and postgres dependencies, and the stale AGENTS.md reference.
Follow-up to the wrangler@4 Node bump: the Trunk Check composite action still installed deps under Node 20, mismatching engines.node >=22. Bump it and update the AGENTS.md prerequisite.
ci: fix Node 22 deploy + remove Supabase knowledge-search
Deploying zsh with
|
| Latest commit: |
febf770
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://1806fe01.zsh.pages.dev |
| Branch Preview URL: | https://next.zsh.pages.dev |
3 tasks
Member
Author
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
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.
This pull request removes three markdown documentation files from the
.github/codebase/directory:ARCHITECTURE.md,CONCERNS.md, andCONVENTIONS.md. These files previously documented the project's architecture, codebase risks, and coding conventions.Key removals:
Documentation Removal
.github/codebase/ARCHITECTURE.md, which described the project's architectural style, system flow, module responsibilities, reused patterns, known risks, and evidence..github/codebase/CONCERNS.md, which outlined codebase risks, technical debt, security concerns, performance/scaling issues, fragile areas, and supporting evidence..github/codebase/CONVENTIONS.md, which defined naming, formatting, import, error/logging, and testing conventions, as well as branch/release practices.