Skip to content

docs: fix outdated guides, document browser, Nix and Eglot setups, and check docs in CI - #876

Merged
psteinroe merged 2 commits into
mainfrom
docs/discussion-fixes
Oct 19, 2026
Merged

psteinroe merged 2 commits into
mainfrom
docs/discussion-fixes

Conversation

@psteinroe

@psteinroe psteinroe commented Oct 19, 2026 •

Copy link
Copy Markdown
Collaborator

Fixes several docs pages that tell users to do things that don't work, and adds the setup docs people kept asking for in GitHub Discussions. Only docs and mkdocs.yml change.

Corrections

  • CI guide: --skip-db doesn't exist, so it's now --disable-db. The action is now supabase-community/postgres-language-server-cli-action instead of the old pglt-cli-action name. Also adds a format check job: format without --write exits non-zero when a file would change.
  • allowStatementExecutionsAgainst was documented as a list of schemas. It's a list of glob patterns matched against host/database (crates/pgls_workspace/src/settings.rs), so a config copied from the guide never enabled execution:
    // before
    "allowStatementExecutionsAgainst": ["public", "testing"]
    // after
    "allowStatementExecutionsAgainst": ["localhost/*", "127.0.0.1/*"]
  • Syntax diagnostics: lists every named-parameter style the tokenizer converts ($name, :name, :'name', :"name", @name). The page used to list only :name and @name.
  • PL/pgSQL: fixes the subject-less first sentence and brings the intro in line with fix(plpgsql): locate syntax errors with plpgsql_check instead of flagging the whole body #862. With plpgsql_check, syntax errors point at the token. Without it, or when plpgsql_check can't check the function, the libpg_query error still covers the whole body.

Editor setup

  • Neovim: vim.lsp.enable('postgres_lsp') for 0.11+, with the legacy require('lspconfig') call kept for older versions. Also notes that the nvim-lspconfig preset sets workspace_required = true with postgres-language-server.jsonc as root marker, so the server doesn't start until postgres-language-server init has created that file. This was the usual reason for "the server doesn't attach".
  • Emacs: describes lsp-mode's lsp-postgres client and adds an Eglot snippet.
  • Multi-root workspaces: one postgres-language-server.jsonc per workspace folder. configuration.md gets a new section on extends for shared settings, which wasn't documented before (path resolution and precedence as implemented in apply_extends). Nested per-directory configs are left out because they're in a separate PR.

New pages

  • Nix: install section for the nixpkgs postgres-language-server package.
  • guides/browser.md: running @postgres-language-server/wasm in a web worker, with Monaco (monaco-languageclient) and CodeMirror (@codemirror/lsp-client), and loading the schema with schema-export + pgls/setSchema. The package APIs come from its README and src/; the third-party client APIs (MonacoLanguageClient, the CodeMirror Transport) were checked against their upstream sources. The Monaco example leaves Monaco service setup to the monaco-languageclient docs, because it differs between versions.

External names were checked against upstream: the action repo, nvim-lspconfig's lsp/postgres_lsp.lua, lsp-mode's clients/lsp-postgres.el, and nixpkgs' pkgs/by-name/po/postgres-language-server. zensical build --strict passes.

CI on docs changes

The Pull Request workflow ignored docs, so docs PRs (including this one) ran no checks, and the site was only built after merging. It now also triggers on docs/**, mkdocs.yml, pyproject.toml and uv.lock. A Detect Changes job (dorny/paths-filter) splits code from docs changes:

  • Docs-only PRs run Format, Check Codegen (it regenerates the rule docs, the CLI reference and the default configuration, so it catches edits to generated sections), and a new Build Docs job running zensical build --strict. Strict mode fails on broken links: I verified that a dead link aborts the build.
  • Code changes run every job as before.
  • Manual runs (workflow_dispatch) run every job.

Addresses:

@psteinroe psteinroe changed the title docs: fix outdated guides and document browser, Nix and Eglot setups docs: fix outdated guides, document browser, Nix and Eglot setups, and check docs in CI Oct 19, 2026
@psteinroe
psteinroe merged commit 21c4862 into main Oct 19, 2026
11 checks passed
@psteinroe
psteinroe deleted the docs/discussion-fixes branch October 19, 2026 06:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant