This repo contains the source for the fish-lsp.dev website, which serves as the documentation to the @ndonfris/fish-lsp project. Eventually, we will remove the main repo's wiki and rely entirely on this site for documentation.

Overall, this repo is a pretty standard astro static site and should be easy to comprehend & maintain.

Tech stack

• pnpm - package manager (pnpm@9)
• Astro 6 - static site (no SSR adapter; builds to dist/)
• Tailwind CSS v4 - via @tailwindcss/vite, brand palette in @theme
• React / Alpine.js - integrations installed and island-ready
• Pagefind - static full-text search over the built HTML
• Vercel - hosting (static; config in vercel.json)
• Fly.io - hosting for the playground container (separate from the static site included in this repo)

Commands

Command	What it does
pnpm dev	Dev server at localhost:4321 (search needs a prior build)
pnpm build	astro build + Pagefind index → dist/
pnpm preview	Serve the built dist/ locally
pnpm check	astro check (diagnostics on .astro/content)
pnpm typecheck	tsc --noEmit

Building

Once the repo is cloned, you can build and run the site locally with the following commands:

pnpm install    # installs dependencies
pnpm build      # builds dist/ + pagefind index
pnpm dev --open # http://localhost:4321

Tip

See CONTRIBUTING.md for more info detailing how to build/run this site locally.

Project layout

> tree -I 'node_modules|dist|.astro' -L 3 # output below is truncated for brevity

./
├── astro.config.ts              # Integrations, custom remark plugins, redirects, Shiki theme, trailingSlash
├── vercel.json                  # Host rules: security/cache headers, cleanUrls, /page/* wildcard redirect
├── tsconfig.json                # Strict TS + path aliases (@components, @layouts, @theme, @typedefs, …)
├── package.json                 # pnpm scripts (dev/build/preview/check/typecheck) + deps
├── build-*.fish                 # Regenerate public/*.svg screenshots with `freeze` (see CONTRIBUTING)
├── public/                      # Served as-is: screenshots (svg/png/gif), fonts/, install.fish, favicon.svg
└── src/
    ├── config.ts                # SITE_ORIGIN + DOCS_ORIGIN — links go absolute in prod, relative in dev
    ├── content.config.ts        # `pages` collection: globs src/content/*.{md,mdx} + zod frontmatter schema
    ├── content/                 # ← THE DOCS. One .md/.mdx per page (installation, commands, features, …)
    ├── pages/
    │   ├── index.astro          # Homepage
    │   ├── playground.astro     # /playground — embeds the browser playground (playground.fish-lsp.dev)
    │   ├── 404.astro
    │   ├── robots.txt.ts        # Dynamic robots.txt (home+docs allowed; playground+schema disallowed)
    │   ├── docs/
    │   │   ├── index.astro      # /docs → redirect to /docs/installation
    │   │   └── [slug].astro     # Renders every content/ page from the `pages` collection
    │   └── schema/…             # /schema/*.json API endpoints (generated — see src/lib/config-schema.ts)
    ├── layouts/
    │   ├── Layout.astro         # Base HTML shell (homepage, standalone pages)
    │   └── DocsLayout.astro     # Docs shell: sidebar nav + prev/next pager + "edit on GitHub" link
    ├── components/              # UI pieces: Header, Footer, BaseHead, Terminal, CodeFile, CommandPrompt, Search, …
    ├── plugins/
    │   ├── remark-codefile.mjs        # fence ```fish /path  desc → <CodeFile>
    │   └── remark-command-prompt.mjs  # fence ```fish prompt (--- splits cmd/output) → <CommandPrompt>
    ├── lib/
    │   ├── config-schema.ts     # SINGLE SOURCE OF TRUTH for fish_lsp_* → builds all /schema/* JSON Schemas
    │   └── fish-info.ts         # Fetches playground container /api/info (6h cache in node_modules/.cache)
    ├── scripts/
    │   └── copy-code.ts         # Client-side copy-to-clipboard buttons for code blocks
    ├── styles/
    │   └── global.css           # Tailwind v4 entry + @theme brand palette/animations (import as @theme/global.css)
    ├── icons/                   # Local SVGs for astro-icon — source new ones from https://icones.js.org
    └── types/
        └── content.ts           # Frontmatter / nav-section / download-option TypeScript interfaces

About the docs

• Most of the content is in Markdown/MDX files under src/content/. The frontmatter schema is defined in src/content.config.ts and validated with Zod.
• The docs are rendered through DocsLayout.astro, which builds the sidebar, the prev/next pager, and the "edit on GitHub" link from filePath.
• The src/components folder contains the UI pieces used in the docs

  including: <Header>, <Footer>, <Terminal>, <CodeFile>, <CommandPrompt>, and <Search>

• Some custom remark plugins are used to render special fenced code blocks, in src/plugins.
• Codeblock highlighting is done with Shiki using the material-theme-ocean theme.
• Mermaid diagrams are rendered client-side with mermaid.js
• Playground page is embedded from a separate container on playground.fish-lsp.dev

Contributing

All contributions are welcome!

Feel free to submit pull requests for typo corrections, formatting fixes, or any other improvements to the documentation.

Tip

For more information on contributing to these web docs, please see the CONTRIBUTING.md file.

License

See MIT License for details.