Docs: 1.7.0 cleanup + homepage refresh#244
Closed
robinskil wants to merge 18 commits into
Closed
Conversation
Add a first-query example, a Key concepts section orienting readers to the docs vocabulary (dataset, external table, collection, view, managed table), and a Next steps link block. Keeps the existing intro, formats table, and architecture diagram. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Collections are superseded by external tables; fold the merged-schema note into the external table definition. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…bles Collections are superseded by external tables: delete the orphaned collections.md page and clean up residual "collection" wording in the data lake overview, the Python SDK page, and the DataGrip page. Reorder the sidebar so Connect comes after the SQL Guide and REST API, matching the learning flow (set up data -> query -> connect clients). Surface Iceberg-backed managed tables in the Data Lake "SQL Tables & Views" section: add a nav entry, a core-concept bullet, and an external-vs-managed pointer on the external tables page. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
getting-started used port 8080, but the actual default (beacon-config BEACON_PORT) and every other page is 5001 — standardize on 5001 in both compose blocks and the verify URL. configuration documented BEACON_ENABLE_FS_EVENTS default as false; the source default is true (1.7.0). Correct the description. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The SQL Guide and Data Lake pages both documented the full CREATE EXTERNAL TABLE syntax and had drifted (formats tables disagreed: one listed ATLAS, the other BBF). Give them distinct roles: - sql/create-table.md is the canonical syntax reference; its formats table is now complete (adds ATLAS, keeps BBF) and gains an Atlas example. - data-lake/external-tables.md is the setup guide: keeps the per-format examples and HTTP listing, drops the duplicated grammar/clauses (IF NOT EXISTS, PARTITIONED BY query example, DROP TABLE, the format-reference table), and links to the syntax reference instead. Also fixes a duplicated sentence. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Swap the abstract hero.png illustration for a HeroQuery component rendered in the home-hero-image slot: a window-framed SQL query (read_netcdf over Argo files) and the table of rows it returns. Communicates what Beacon does far better than the illustration. The component is theme-aware (VitePress CSS vars, adapts to light/dark) and reuses the existing wide-screenshot hero layout. Frontmatter image is kept so the two-column has-image layout still applies. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add a SQL/Python tab toggle to the homepage hero card: SQL shows the query and its Arrow result table; Python shows the same query via the Beacon Python SDK (client.sql_query(...).to_pandas_dataframe()) rendering a pandas-style DataFrame with an index column. Vertically center the hero card against the heading/tagline/buttons by aligning the hero container and image flex items to center. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Trim the Python snippet to 4 lines (matching the SQL block) and pin the code area's min-height, so switching tabs no longer grows the card or shifts the result table. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The hero card now plays a sequence on load (and on tab switch): the code is typed out with a cursor, a brief "running query" spinner shows, then the result rows fade in. Implemented with pre-tokenized code so syntax colors survive char-by-char reveal. SSR/no-JS/reduced-motion render the finished state directly, and the card height stays pinned across every phase (code min-height + rows always laid out, only faded). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The card server-rendered its finished state (rows visible), so on load the browser painted the full result, then JS rewound to the typing start — a visible flash of rows appearing and disappearing. Initialise the component in the typing-start state instead, so the first painted frame matches where the animation begins. onMounted drives it forward (or jumps to the finished state under prefers-reduced-motion). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Rework the hero animation: the code now uses the full card height while typing, and when the query runs a results drawer slides up from the bottom (~half the card) showing the loading spinner, then fills with the rows. Because the result area no longer sits below the code, the Python tab can show the fuller SDK example (sql_query with the multi-line query and to_pandas_dataframe). Card height is fixed and equal across both tabs. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Beneath the format/integration badges, add an ArchDiagram component showing a typical Beacon setup: a Jupyter notebook client on the internet querying Beacon on EC2 (SQL / Flight SQL), which reads files from an S3 bucket. Animated with flowing data packets along the connectors. Pure SVG + CSS animation (works under SSR/no-JS), theme-aware via VitePress CSS vars, honors prefers-reduced-motion, and hides sub-labels on narrow screens. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The architecture diagram now toggles between two topologies, matching the hero's tab pattern: - Cloud (AWS): Beacon on EC2 reading from an S3 bucket (object storage) - On-premise: Beacon as a local process reading NetCDF/Parquet from the same server's local disk Both keep the Jupyter notebook connecting over the internet via SQL / Flight SQL. Implemented by parameterizing the region label, storage node, and second connector label off a reactive mode; animation and theming unchanged. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Third toggle option alongside Cloud and On-premise: Local — Beacon, the data files, and the Jupyter notebook all on one machine (localhost), so there is no internet hop. Regions are now data-driven per mode, so Local renders as a single "Your laptop" box around all three nodes. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace the single toggled diagram with three compact deployment cards shown together — Cloud (AWS), On-premise, Local — each a simple vertical client -> Beacon -> storage flow with a subtle downward flow dot. Communicates Beacon's deployment flexibility at a glance, renders fully without JS, and stacks responsively on narrow screens. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The cards sit inside the badges container, so flex-basis wrapped the third onto a second line. Use an explicit 3-column grid (cards shrink to fit instead of wrapping); collapse to a single column under 640px. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Give the homepage structure between its card sections: - home-features-before: a "Built for scientific data" heading + subtitle so the feature grid (previously unlabeled) has context and is set off from the deployment cards above it. - home-features-after: a get-started CTA band with the docker pull command and Get started / GitHub buttons. Both are static, theme-aware components wired through VitePress home slots. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The heading used a negative bottom margin, which pulled the feature grid up over the subtitle. Use positive margins so it sits clearly above the cards. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Documentation update for the 1.7.0 docs set plus a VitePress homepage refresh, aiming to clarify core concepts (datasets/external tables/managed tables/views), fix a couple of defaults, and modernize the landing experience with new interactive/theme-aware components.
Changes:
- Updated 1.7.0 docs to reflect external tables/managed tables terminology, improved onboarding content, and corrected default port / FS events defaults.
- Split “external tables” content into a SQL grammar reference vs. a setup/how-to guide and removed the orphaned collections page.
- Refreshed the homepage hero and feature sections with new Vue components (animated query card, deployment cards, CTA) and updated theme layout slots.
Reviewed changes
Copilot reviewed 16 out of 16 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/docs/1.7.0/sql/create-table.md | Adds/clarifies format reference + Atlas/Zarr examples and points to the setup guide. |
| docs/docs/1.7.0/introduction.md | Adds “first query”, key concepts, and next-step navigation links. |
| docs/docs/1.7.0/getting-started.md | Fixes Docker Compose examples to use the default HTTP port 5001. |
| docs/docs/1.7.0/data-lake/index.md | Updates core concepts to external/managed tables + views (replacing collections wording). |
| docs/docs/1.7.0/data-lake/external-tables.md | Refocuses page as a setup guide and links to SQL reference for full grammar. |
| docs/docs/1.7.0/data-lake/configuration.md | Corrects/clarifies BEACON_ENABLE_FS_EVENTS default and behavior. |
| docs/docs/1.7.0/data-lake/collections.md | Removes deprecated/orphaned collections page. |
| docs/docs/1.7.0/connect/jetbrains-datagrip.md | Updates “collections” wording to “external tables”. |
| docs/docs/1.7.0/connect/beacon-python-sdk.md | Renames section heading to remove “collections” terminology. |
| docs/.vitepress/theme/index.js | Registers new homepage components and wires them into VitePress home slots. |
| docs/.vitepress/theme/custom.css | Adjusts hero layout to better center the new hero component. |
| docs/.vitepress/theme/components/HeroQuery.vue | New animated SQL/Python “live query” hero component. |
| docs/.vitepress/theme/components/GetStartedCta.vue | New “Get started” CTA band for the homepage. |
| docs/.vitepress/theme/components/FeaturesIntro.vue | Adds a heading/intro block above the feature grid. |
| docs/.vitepress/theme/components/ArchDiagram.vue | Adds deployment “cards” showing Beacon flows (cloud/on-prem/local). |
| docs/.vitepress/config.mts | Reorders sidebar sections and surfaces Managed Tables appropriately. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| </script> | ||
|
|
||
| <template> | ||
| <div class="hero-query" aria-label="Example Beacon query and its results"> |
| <span class="hq-dot"></span> | ||
| <span class="hq-dot"></span> | ||
| <div class="hq-tabs" role="tablist"> | ||
| <button |
| :aria-selected="tab === 'sql'" | ||
| @click="tab = 'sql'" | ||
| >SQL</button> | ||
| <button |
|
|
||
| <div class="depcards"> | ||
| <article v-for="c in cards" :key="c.key" :class="['depcard', 'accent-' + c.key]"> | ||
| <div class="depcard-head"><span class="dh-ico">{{ c.icon }}</span>{{ c.title }}</div> |
| <template v-for="(n, i) in c.nodes" :key="i"> | ||
| <div class="dep-node"> | ||
| <img v-if="n.logo" class="dn-logo" :src="logo" alt="" /> | ||
| <span v-else class="dn-ico">{{ n.ico }}</span> |
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.
Documentation pass for 1.7.0 plus a homepage refresh.
Docs content (
docs/docs/1.7.0/)collections.md, cleaned up residual "collection" wording in the data-lake overview, Python SDK, and DataGrip pages.sql/create-table.mdis the canonical syntax reference (formats table reconciled — Atlas + BBF),data-lake/external-tables.mdis the setup guide; removed the duplicated grammar that had drifted.getting-started.mdHTTP port8080 → 5001(the real default, matching every other page);configuration.mdBEACON_ENABLE_FS_EVENTSdefaultfalse → true(per source).Homepage (
docs/.vitepress/theme/)All components are theme-aware (VitePress CSS vars), responsive, and verified with
vitepress build.🤖 Generated with Claude Code