Skip to content

Commit e0c4d70

Browse files
kvlongekvlonge
committed
Add the SQLQuack website and browser playground
An Astro Starlight site in website/, sharing SQLClean's structure, styling and components: the homepage, docs pages taken from the README and the command's help, a diagnostics reference generated from the code registry, and a playground page. Coverage figures are placeholders in src/data/figures.json. website/wasm is the playground's engine, a thin wasm-bindgen crate over the existing crates, kept out of the main workspace as fuzz/ is. Translated SQL runs in DuckDB-WASM in the browser. The Website workflow is manual only and deploys nothing.
1 parent 969e9d2 commit e0c4d70

71 files changed

Lines changed: 12052 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/website.yml‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
name: Website
2+
3+
# Builds the site and checks its links and branding. Manual only, and it never deploys: the site is
4+
# not public yet. Add push and pull_request triggers, and a deploy job, once publishing is approved.
5+
on:
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
11+
concurrency:
12+
group: website-${{ github.ref }}
13+
cancel-in-progress: true
14+
15+
jobs:
16+
build:
17+
name: Build the website
18+
runs-on: ubuntu-24.04
19+
defaults:
20+
run:
21+
working-directory: website
22+
steps:
23+
- uses: actions/checkout@v4
24+
25+
- uses: actions/setup-node@v4
26+
with:
27+
node-version: 22
28+
cache: npm
29+
cache-dependency-path: website/package-lock.json
30+
31+
- name: Check the diagnostics reference matches the registry
32+
run: python3 scripts/generate_diagnostics.py --check
33+
34+
- name: Install dependencies
35+
run: npm ci
36+
37+
- name: Build
38+
run: npm run build
39+
40+
- name: Check links
41+
run: python3 scripts/check_links.py dist

‎website/.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
node_modules/
2+
dist/
3+
.astro/
4+
public/playground/engine/
5+
wasm/target/

‎website/.nvmrc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
22

‎website/README.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Website
2+
3+
The SQLQuack website: the homepage at `/`, the documentation at `/docs/` and the playground at
4+
`/playground/`, built as one [Astro Starlight](https://starlight.astro.build) site. It shares its
5+
structure, styling and components with the SQLClean and SQLBuild websites.
6+
7+
- `public/index.html` and `public/styles.css`: the homepage, plain static HTML and CSS. Its terminal
8+
examples are real `sqlquack` output on a small orders example, trimmed where marked `…`.
9+
- `src/content/docs/docs/`: the documentation pages (MDX). `src/sidebar.json` holds the sidebar
10+
and `src/navigation.mjs` the redirects. `STYLE.md` is the style guide for these pages.
11+
- `src/content/docs/docs/diagnostics/reference.mdx` is generated from
12+
`crates/sqlquack-core/src/diagnostics/constants.rs` by `scripts/generate_diagnostics.py`;
13+
`--check` fails while the two differ.
14+
- `src/components/`: the page layout, header and page title, replacing Starlight's defaults.
15+
- `public/fonts/`: self-hosted fonts, each with its licence.
16+
- `public/playground/`: the playground page. `wasm/` is its engine, a thin wasm-bindgen crate over
17+
the existing SQLQuack crates (parse, Snowflake checks, name checks, conversion under the built-in
18+
policy), kept out of the main Cargo workspace as `fuzz/` is. `scripts/build_engine.sh` builds it
19+
into `public/playground/engine/`, which is not committed. Translated SQL runs in DuckDB-WASM,
20+
loaded from jsDelivr on first use.
21+
22+
The logo uses the SQLQuack icon from `sqlstack-io/sqlstack` (`assets/icons/sqlquack.png`); the
23+
footer's SQLStack symbols are unchanged copies from the same repository.
24+
25+
The Website workflow builds the site and checks its links when run by hand. It does not deploy,
26+
and nothing publishes the site yet.
27+
28+
Requires Node 22.12 or newer.
29+
30+
```bash
31+
rustup target add wasm32-unknown-unknown
32+
cargo install --locked wasm-bindgen-cli --version =0.2.130
33+
scripts/build_engine.sh # the playground engine; prints its size
34+
npm install
35+
python3 scripts/generate_diagnostics.py # after changing the diagnostic registry
36+
npm run dev # live preview
37+
npm run build # static site in dist/, including the search index
38+
npm run preview # serve dist/
39+
python3 scripts/check_links.py dist
40+
npm test # Playwright: branding and navigation
41+
```

‎website/STYLE.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Docs style guide
2+
3+
These rules apply to every page under `website/src/content/docs/`. Pages that follow them well:
4+
`cli/check.mdx`, `diagnostics/overview.mdx` and `policy.mdx`.
5+
6+
## Write for users
7+
8+
- Document what a user does, sees and must decide: commands, flags, config keys, defaults, limits,
9+
diagnostic codes and messages, output, exit codes, and the fix for each problem.
10+
- Leave out how SQLQuack works inside: crate layout, internal tree formats, building blocks and
11+
internal structures. Include a mechanism only when the user must act
12+
on it, and then say what to do (for example, which flag forces a fresh check).
13+
- Never document behaviour you haven't checked in the source or with the real `sqlquack` command.
14+
Paste real output, trimmed.
15+
16+
## Structure
17+
18+
- Lead with what the feature does and a short example: a command, a config block or the output a
19+
user sees.
20+
- Organise sections around the user's tasks ("Declaring a schema", "Allowing a divergence"), not
21+
around the implementation.
22+
- One topic per section. Put flags, config keys and codes in reference tables near the top or
23+
bottom, and details that rarely matter in a short "Details" or "Limitations" list at the end.
24+
- Keep headings that other pages link to. Before renaming or removing one, run
25+
`grep -rn "<page>#" website/src` and update the links.
26+
27+
## Tables
28+
29+
- Use a table for anything that varies by code, flag or policy: meaning, defaults and caveats.
30+
Don't write a paragraph per code.
31+
- Use tables for flags, config keys with defaults, exit codes, diagnostic codes and fields.
32+
- Keep cells short. Put a long explanation in the text below the table.
33+
34+
## Sentences
35+
36+
- Write short, plain sentences in the present tense. One idea per sentence.
37+
- Give every diagnostic an example where it matters, such as the SQL that triggers it and the SQL
38+
that fixes it.
39+
- Use neutral orders-style examples (orders, customers, products, payments).
40+
41+
## No history
42+
43+
- Describe the product as it is. Don't write "now", "no longer", "used to", "earlier releases",
44+
"as before", "upgrade note" or "previously". History belongs in `CHANGELOG.md`.
45+
- Drop notes about legacy syntax and migrations from old versions once the error message itself
46+
tells the user what to do.
47+
48+
## Changing a page
49+
50+
- When a feature changes a page, edit the page into shape: put the new fact in the section it
51+
belongs to, update tables and examples, and remove what is no longer true. Don't append a
52+
paragraph to the end of a section or page.
53+
- Don't repeat a rule that another page owns. Link to it instead, for example to
54+
`policy#sessions` for session parameters.
55+
56+
## Measured figures
57+
58+
- State only measured figures, each with its basis: the commit, the policy and the command that
59+
reproduces it. Never present a figure as exhaustive or as proof for every input.
60+
- `diagnostics/reference.mdx` is generated from the code registry by
61+
`scripts/generate_diagnostics.py`; edit the registry, not the page.

‎website/astro.config.mjs‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
import { defineConfig } from 'astro/config';
2+
import starlight from '@astrojs/starlight';
3+
import starlightLlmsTxt from 'starlight-llms-txt';
4+
import { sqlquackDark, sqlquackLight } from './src/code-themes.mjs';
5+
import { redirects, sidebar } from './src/navigation.mjs';
6+
import { figuresIntegration } from './src/figures.mjs';
7+
8+
export default defineConfig({
9+
// Placeholder: the public domain is not chosen yet.
10+
site: 'https://sqlquack.io',
11+
redirects,
12+
integrations: [
13+
figuresIntegration(),
14+
starlight({
15+
title: 'SQLQuack',
16+
description: 'A Snowflake SQL compiler: parse, check and translate to DuckDB, or refuse with a precise reason.',
17+
logo: {
18+
light: './src/assets/logo-light.png',
19+
dark: './src/assets/logo-dark.png',
20+
replacesTitle: true,
21+
},
22+
favicon: '/favicon.png',
23+
head: [
24+
{ tag: 'meta', attrs: { property: 'og:image', content: 'https://sqlquack.io/assets/og-sqlquack.png' } },
25+
{ tag: 'meta', attrs: { property: 'og:image:width', content: '1200' } },
26+
{ tag: 'meta', attrs: { property: 'og:image:height', content: '630' } },
27+
{ tag: 'meta', attrs: { name: 'twitter:image', content: 'https://sqlquack.io/assets/og-sqlquack.png' } },
28+
],
29+
social: [
30+
{ icon: 'github', label: 'GitHub', href: 'https://github.com/sqlstack-io/sqlquack' },
31+
],
32+
components: {
33+
PageFrame: './src/components/PageFrame.astro',
34+
TwoColumnContent: './src/components/TwoColumnContent.astro',
35+
Header: './src/components/Header.astro',
36+
PageTitle: './src/components/PageTitle.astro',
37+
SiteTitle: './src/components/SiteTitle.astro',
38+
Pagination: './src/components/Pagination.astro',
39+
ThemeSelect: './src/components/ThemeSelect.astro',
40+
Footer: './src/components/Footer.astro',
41+
},
42+
customCss: ['./src/styles/fonts.css', './src/styles/sqlquack.css'],
43+
expressiveCode: {
44+
themes: [sqlquackDark, sqlquackLight],
45+
defaultProps: {
46+
// Plain boxes for shell snippets, without the fake terminal title bar.
47+
overridesByLang: { 'bash,sh,shell,zsh,console,powershell': { frame: 'none' } },
48+
},
49+
styleOverrides: {
50+
borderRadius: '2px',
51+
borderWidth: '1px',
52+
codeFontFamily: 'var(--sl-font-mono)',
53+
codeFontSize: '13px',
54+
codeLineHeight: '1.65',
55+
uiFontFamily: 'var(--sl-font)',
56+
frames: {
57+
shadowColor: 'transparent',
58+
inlineButtonBorder: 'transparent',
59+
inlineButtonBackgroundIdleOpacity: '0',
60+
inlineButtonBackgroundHoverOrFocusOpacity: '0.08',
61+
inlineButtonForeground: 'var(--sqq-muted)',
62+
frameBoxShadowCssValue: 'none',
63+
editorTabBarBackground: 'var(--sqq-code-bg)',
64+
editorActiveTabBackground: 'var(--sqq-code-bg)',
65+
editorActiveTabIndicatorTopColor: 'var(--sqq-primary)',
66+
editorTabBarBorderBottomColor: 'var(--sqq-line)',
67+
terminalTitlebarBackground: 'var(--sqq-code-bg)',
68+
terminalTitlebarBorderBottomColor: 'var(--sqq-line)',
69+
terminalTitlebarDotsOpacity: '0.35',
70+
terminalBackground: 'var(--sqq-code-bg)',
71+
},
72+
borderColor: 'var(--sqq-line)',
73+
},
74+
},
75+
sidebar,
76+
plugins: [
77+
starlightLlmsTxt({
78+
projectName: 'SQLQuack',
79+
description:
80+
'SQLQuack parses Snowflake SQL, reports what Snowflake would reject with coded diagnostics, and converts it into DuckDB SQL or refuses it with a precise reason.',
81+
}),
82+
],
83+
}),
84+
],
85+
});

0 commit comments

Comments
 (0)