diff --git a/.github/assets/shot-navigator.png b/.github/assets/shot-navigator.png new file mode 100644 index 0000000..d6bdb2a Binary files /dev/null and b/.github/assets/shot-navigator.png differ diff --git a/README.md b/README.md index c905f4e..5863497 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@ development toolbar. [Product page](https://opace.agency/tools/astro/visual-editor/) · [Install](#install) · [Try the demo](#try-the-repository-demo) · +[How this compares](#how-this-compares) · [Configuration](#configuration) · [Security](./SECURITY.md) · [Contributing](./CONTRIBUTING.md) · [Opace open-source portfolio](https://github.com/OpaceDigitalAgency/OpaceDigitalAgency) @@ -50,6 +51,13 @@ with a one-click explanation: ![The visual builder with a selected block toolbar, a locked chip and the docked inspector](./.github/assets/shot-builder.png) +**Page structure navigator.** Every group, section, row and block on the +page, Elementor-style: click any item to select and scroll to it on the +canvas, drag or use move controls to reorder, and see lock state at a +glance without opening the rendered page's own toolbar: + +![The Page structure navigator tree showing nested groups, sections, rows and blocks with a selected paragraph highlighted on the canvas](./.github/assets/shot-navigator.png) + **SEO editing.** Title, description, keywords, canonical URL, Open Graph fields and robots directives in one form, each field capability-checked against its real source before it is offered: @@ -157,22 +165,105 @@ This package provides: It adds no production route, editor client or public write endpoint. +## How this compares + +Most "Astro CMS" tools solve a different problem: they give a hosted or +admin-panel UI for editing structured content records (Keystatic, Sitepins, +Writenex, Sveltia, Decap), or overlay a hosted headless CMS on top of a live +preview (Sanity, Netlify Visual Editor, TinaCMS). None of them write directly +to `.astro` source, and most need an external account or hosting. + +The closest actual peer is [Stacki](https://github.com/flowtricks/stacki), a +free, open-source **desktop app** that also edits Astro projects locally with +no CMS backend. It reaches that goal through a different mechanism: a +component/props palette in a separate Electron app, rather than click-any- +rendered-text editing inside Astro's own Dev Toolbar. Stacki currently ships +a visual style panel that this package does not yet have — see +[Roadmap](#roadmap-and-requests). + +| | This package | Stacki | Headless-CMS tools (Keystatic, Sitepins, TinaCMS, …) | +| ------------------------------------ | ----------------------------------------------------- | --------------------------- | ---------------------------------------------------- | +| Where you edit | In-browser, on the rendered page, via the Dev Toolbar | Separate desktop app | Separate admin UI or hosted studio | +| Writes to `.astro` source directly | Yes | Yes, via its own page model | No — content records only | +| Zero-config on an unannotated page | Yes | No | No | +| Style/design editing | Not yet (roadmap) | Yes | No | +| External account or hosting required | No | No (GitHub CLI optional) | Usually yes | + +### Frequently asked comparisons + +#### Is Astro Visual Editor a CMS? + +No. A CMS stores content in its own records (a database or managed content +files) and your site queries it. Astro Visual Editor has no content store at +all: it edits your existing `.astro`, Markdown, JSON and YAML source files in +place, with every change reviewable as an ordinary Git diff. If you want a +hosted editing workflow for non-technical users today, a CMS is still the +right tool — the two can coexist in the same project. + +#### How is this different from Stacki? + +[Stacki](https://github.com/flowtricks/stacki) is a free, open-source desktop +app that opens an Astro project and edits it through a component/props +palette. Astro Visual Editor pursues the same goal — visually edit real Astro +source with no CMS backend — but runs inside Astro's own Dev Toolbar in the +browser, so you click and type on the actual rendered page rather than +working in a separate app. Stacki has a style panel today; this package edits +any unannotated page with zero setup and reviews every change as a validated +batch before writing. + +#### Do I still need Sanity, Netlify Visual Editor or TinaCMS? + +Those tools give hosted, authenticated editing of CMS-managed content with a +live preview — the right choice when non-technical editors need to publish +from a browser without a local dev server. Astro Visual Editor solves the +other half: editing the source files themselves during local development, +with no accounts, schemas or migration. Many teams would use one of each. + +#### How is this different from Keystatic, Sitepins, Decap or Sveltia? + +Those are Git-based content editors: a separate admin UI that reads and +writes Markdown/JSON/YAML content files (usually `src/content/`), commit by +commit. They never touch `.astro` files and never show you the rendered page +while you edit. Astro Visual Editor edits on the rendered page itself and +writes to any supported source file that owns the value, including `.astro` +component markup. + +#### Does it work on a deployed production site? + +Not yet, by design: the editor and its write endpoint exist only during +`astro dev` and are excluded from production builds entirely. An +authenticated, Git-API-backed deployed mode is on the +[roadmap](#roadmap-and-requests). + +#### Does it work on my existing Astro site without changes? + +On conventional pages, yes — enable the editor and unique literal text +becomes editable immediately, with safe structural matches becoming +drag-reorderable sections. Pages that compose content from many sources can +add annotations or mappings to extend coverage; nothing is ever guessed, and +unprovable edits are refused rather than written. + ## Roadmap and requests Zero-step editing covers conventional Astro pages today. Planned for the next betas, roughly in order: +- **Full design control** — Elementor/Divi-grade style editing rather than + today's read-only Design tab: typography (family, size, weight, line + height), spacing, colours, backgrounds, borders and shadows, edited on the + canvas and written back only where the owning CSS or Astro style source + can be proven safely. The nearest open-source peer (Stacki) already ships + a style panel; closing this gap is the top priority. +- **Typed component insertion** — a form-driven way to add a whole component + instance and configure its typed props (in the spirit of reading a + component's declared prop types and generating matching form fields), + alongside today's literal-text and structured-path editing. - **Dynamic and collection routes** — inferring the owning content file for `[slug]` pages and Content Collections without any mapping. - **Repeated-text disambiguation** — safe automatic resolution when the same string appears in several files (i18n locales, repeated CTAs). - **Client islands** — mapping text rendered by React/Vue/Svelte islands back to their component source. -- **Full design control** — Elementor/Divi-grade style editing rather than - today's read-only Design tab: typography (family, size, weight, line - height), spacing, colours, backgrounds, borders and shadows, edited on the - canvas and written back only where the owning CSS or Astro style source - can be proven safely. - **Light and dark mode** — theme switching for the editor panel, plus light/dark variants in the bundled demos and planned starter themes. - **Structured data** — schema.org/JSON-LD editing alongside the existing SEO @@ -181,6 +272,9 @@ next betas, roughly in order: HMR introduces new content mid-session. - **Images and assets** — replacing images from the canvas with source-safe asset handling. +- **Client-accessible deployed editing** — an authenticated, SSR-hosted mode + that writes through the Git provider API instead of the local filesystem, + for non-technical editors on a deployed site rather than only `npm run dev`. Want one of these sooner, or something we have not planned? diff --git a/packages/astro-visual-editor/README.md b/packages/astro-visual-editor/README.md index 73f994d..52e3b77 100644 --- a/packages/astro-visual-editor/README.md +++ b/packages/astro-visual-editor/README.md @@ -46,6 +46,11 @@ on the selected block, persistent lock chips on locked content: ![The visual builder with a selected block toolbar, a locked chip and the docked inspector](https://raw.githubusercontent.com/OpaceDigitalAgency/astro-visual-editor/main/.github/assets/shot-builder.png) +The Page structure navigator — every group, section, row and block, +Elementor-style, with click-to-select and drag or move-control reordering: + +![The Page structure navigator tree showing nested groups, sections, rows and blocks with a selected paragraph highlighted on the canvas](https://raw.githubusercontent.com/OpaceDigitalAgency/astro-visual-editor/main/.github/assets/shot-navigator.png) + The SEO form with all seven fields capability-checked against their real source, and the review tray where every change waits for one validated save: @@ -60,22 +65,44 @@ multi-file batch) and **Plain (zero setup)** (an unannotated page edited entirely by inference). The demo also bundles `@astrojs/sitemap` and real head markup so SEO editing is proven against a conventional Astro site. +## How this compares + +Most "Astro CMS" tools (Keystatic, Sitepins, Writenex, Sveltia, Sanity, +Netlify Visual Editor, TinaCMS) edit structured content records through a +separate admin UI or hosted studio, not `.astro` source. The closest actual +peer is [Stacki](https://github.com/flowtricks/stacki), a free open-source +desktop app that also edits Astro projects locally with no CMS backend, via +a component/props palette rather than click-any-text editing inside the Dev +Toolbar. Stacki already ships a style panel this package does not yet have — +see Roadmap below. Full comparison in the +[repository README](https://github.com/OpaceDigitalAgency/astro-visual-editor#how-this-compares). + +**Is it a CMS?** No — there is no content store. It edits your existing +`.astro`, Markdown, JSON and YAML source files in place, reviewable as an +ordinary Git diff, and can coexist with any CMS. **Do I still need Sanity, +Netlify Visual Editor or TinaCMS?** Those provide hosted editing of +CMS-managed content for non-technical publishers; this edits the source +itself during local development. Many teams would use one of each. More +comparisons (Stacki, Keystatic, Sitepins, Decap, Sveltia) in the +[repository FAQ](https://github.com/OpaceDigitalAgency/astro-visual-editor#frequently-asked-comparisons). + ## Roadmap and requests Zero-step editing covers conventional Astro pages today. Planned for the next betas, roughly in order: +- **Full design control** — Elementor/Divi-grade style editing rather than + today's read-only Design tab. The nearest open-source peer already ships a + style panel; closing this gap is the top priority. +- **Typed component insertion** — a form-driven way to add and configure a + whole component instance from its typed props, alongside today's literal- + text and structured-path editing. - **Dynamic and collection routes** — inferring the owning content file for `[slug]` pages and Content Collections without any mapping. - **Repeated-text disambiguation** — safe automatic resolution when the same string appears in several files (i18n locales, repeated CTAs). - **Client islands** — mapping text rendered by React/Vue/Svelte islands back to their component source. -- **Full design control** — Elementor/Divi-grade style editing rather than - today's read-only Design tab: typography (family, size, weight, line - height), spacing, colours, backgrounds, borders and shadows, edited on the - canvas and written back only where the owning CSS or Astro style source - can be proven safely. - **Light and dark mode** — theme switching for the editor panel, plus light/dark variants in the bundled demos and planned starter themes. - **Structured data** — schema.org/JSON-LD editing alongside the existing SEO @@ -84,6 +111,9 @@ next betas, roughly in order: HMR introduces new content mid-session. - **Images and assets** — replacing images from the canvas with source-safe asset handling. +- **Client-accessible deployed editing** — an authenticated, SSR-hosted mode + writing through the Git provider API for non-technical editors, not just + local `npm run dev`. Want one of these sooner, or something we have not planned?