Docs menu

Your first edit

A tour of the studio in local mode, from opening an entry to saving it, with the body editor, images and page trees.

In local mode the studio runs inside astro dev and saves straight to the files on your computer. Start the dev server and open /admin/ on it:

npm run dev

Home

The first screen, headed Content, lists your collections, with how many entries each has. Collections with singleton: true, such as site settings, are listed under Settings. On a wide screen that list is a pane on the left, with Media, Redirects and View site under Site, and it stays there as you open things beside it (see "Panes" below). Until you choose something, the rest of the window is empty. On a narrow one, the first screen also says when each collection was last edited, and the top bar takes two lines: the site's name with your picture, then the Content menu, which reaches the same collections, and the Site menu, with Media, Redirects and View site. Your picture, at the end of the top bar, opens a menu with Appearance: System follows your computer's light or dark setting, and Light or Dark keeps the studio that way in this browser. In local mode the picture is the initials of git's user.name; signed in, it's your account's, and in GitHub mode your GitHub picture. The menu says who you are.

A collection's list

A collection opens as a table of its entries: title, any columns you name in listFields, when each was edited, and its status. Where an entry could be something other than live (in a collection with a draft field or a schedule, and in every collection in the cloud, where a new entry starts as a draft), the status starts with a word on its colour: Live in green, Scheduled in violet, Draft (draft: true) and Unpublished in grey. Words such as Read only follow it. Search filters by title, and the column headings sort.

New entry starts one. Its file is named after its title the first time you save it. A singleton skips the list and opens its one entry.

The entry editor

The title field is the page's heading. Below it are tabs: Content holds the main fields, in your schema's order, then the body, and Details the secondary fields: slugs, dates, tags, draft, ordering and SEO. The arrow keys move between tabs. A field's .meta({ placement: 'details' }) or 'main' overrides the rule, and a collection can add tabs of its own, such as SEO (see Fields).

The top bar also has the entry's status ("No changes", "Unsaved changes", "Saved just now", or "Read only" for an entry you can't edit), after its coloured word as in the list ("Live · Saved just now"), Save, and a "…" menu. The dot before the status pulses while a save runs. The status has a line of its own, under the entry's title, or on a narrow screen under the way back to the list, so the bar keeps its size as the status changes. The menu has:

  • View on site and Copy page address, for a collection with a url. The address is the page's full address, on Astro's site when your config sets one, so one copied while working locally is the live page's.
  • Copy editing link, the studio's address for this entry, to send to a colleague. It opens the entry after a reload, and after signing in.
  • Duplicate, which opens a new entry with everything copied, " (copy)" after its title and a new address. Nothing is saved until you save it; the new file then starts as the original's own text, comments and all, with your changes. In a collection of pages, the copy goes right after the original, without its subpages.
  • Unpublish…, in a collection with a draft field, for whoever may publish. After asking, it sets draft: true and saves (or publishes), and the site leaves the entry out the next time it's built. A draft has Make it live instead, which sets draft: false.
  • Discard changes…, while there are unsaved changes. After asking, it puts the entry back as it was last saved, without leaving it.
  • Delete.

After a copy, the status says "Link copied" for a few seconds. Where the browser doesn't allow copying (a site on plain http), the link is shown selected, ready for Ctrl+C (⌘C on a Mac).

Panes

On a screen 768 pixels wide or more, the studio is panes, side by side across the whole width: your collections first, then a collection's list, then the entry. With nothing chosen, your collections are the only pane. Choosing a collection opens its list in a pane beside the collections, and an entry you open from it opens beside the list, which stays as it is, with the open entry marked. The list pane has a search field, Sort and New entry, and Show when some entries are drafts or need a developer; a collection of pages shows its outline there instead, with a search field, each page's “…” menu and New page. Each pane scrolls on its own, and the collections are always one click away. To make more room, collapse a pane with the button at the end of its header: it becomes a narrow strip, and stays one in this browser until you click the strip. When the panes don't all fit, the studio folds the earlier ones into strips itself. Moving to another entry asks first when the open one has unsaved changes. Narrower than 768 pixels, the studio shows one screen at a time, with the top bar's menus.

What Save does

Nothing is written until you press Save, or Ctrl+S (⌘S on a Mac). There's no autosave: every write makes Astro reload the site, and a half-typed value could fail your schema.

When you save:

  • Your schema checks the values. Problems show under their fields and in a summary at the top, and nothing is written.
  • Only the entry's own file changes, apart from the page-tree cases below.
  • The change is spliced into that file: only the bytes of the values you changed are rewritten. Comments, quoting, key order and line endings stay as they were, and in the body only the blocks you touched change.
  • If the file changed on disk since you opened it, nothing is written, and the studio offers Reload this entry.

The one exception is frontmatter with YAML anchors, aliases or tags, which can't be edited in place. It's rewritten in a standard layout, and the studio says so.

The body editor

Markdown, Markdoc and MDX bodies open in a writing view, with a toolbar for bold, italic, headings, lists, quotes, code, links and images. The toolbar's text style menu makes the line a paragraph or a heading, from the level where the collection's headings start (headingStart, 2 unless you set it) down to 6; it shows the style where the cursor is. As you scroll a long body, the toolbar stays at the top of the window. The link dialog searches your pages by title.

Markdoc tags from markdoc.config.mjs, and MDX components you declare in vesper.config.ts, are blocks: a frame with a Settings button, whose form comes from the tag's attributes.

  • Type / at the start of a line or after a space to insert a block or a table, or use the toolbar's Insert menu. Both offer only what fits at the cursor.
  • Arrow onto a block to select it. Enter opens its settings, and Alt+↑ and Alt+↓ move it.
  • Escape leaves a block, then moves from the text to the toolbar.

Tables are grids. Arrow onto one and press Enter to move into its cells: the arrow keys move between cells, Enter or F2 edits one, and Tab goes on to the next, adding a row after the last. Table actions, the "…" above the table or Shift+F10 on a cell, insert, move and delete rows and columns, and align a column. More in Markdoc and MDX.

Anything the writing view can't save back exactly is a source block, a dashed box such as "HTML, kept as written": HTML, comments, footnotes, imports, undeclared MDX components, and tables it can't show as a grid. They're kept byte for byte, and Edit as text changes one as plain text. Edit as Markdoc (or Markdown, or MDX) shows the whole body as text, exactly as it's saved.

A body your site's build would fail on, such as a tag without a required attribute, can't be saved; the problem shows on its block. More in Markdoc and MDX.

Add an image

Use Choose image in an image field, or Image in the body's toolbar. Both open one dialog: upload from your computer, or choose an image already in the site. Large photos are scaled down, turned upright and stripped of location data, and a file the site already has is offered for reuse.

Then describe the image. Alt text is required unless you mark it decorative, an image that adds nothing a reader needs.

New images go to src/assets/<collection>/, or beside the image they replace, and the entry stores a path relative to its own file, so Astro's image() processes them. The image file is written as soon as it's uploaded; the entry changes when you save. For focal points and crops, see Images.

Pages in a tree

A collection with tree: true opens as an outline: pages as they nest on the site, each with its address. Each page's "…" menu has Add child page, Duplicate, Move to…, Move up, Move down and Delete. From a page, the right arrow or Shift+F10 reaches its menu, and Alt+↑ and Alt+↓ move it. You can drag pages too. The search field above the outline narrows it to the pages that match.

  • Move up and Move down rewrite the folder's _order.yaml.
  • Add child page opens a new page under that one. Saving it adds it to the folder's _order.yaml, if there is one. A parent that's a single file becomes a folder's section page, so about.md moves to about/index.md, at the same address.
  • Move to… asks for the new parent and the last part of the address. Review move says what will happen, such as "8 links on other pages will be updated", before anything changes. The move writes the page and every page under it, both folders' _order.yaml, a redirect for each old address in vesper.redirects.yaml, and the links to them on other pages.

More in Pages and URLs.

Edit this page

In astro dev, Astro's toolbar gets a Vesper app, a crescent. On any page of your site it lists the entries the page shows, each linked to its editor, then the ones it only lists.

It sees only entries the page reads through vesper:content, a drop-in for astro:content:

---
// was: import { getCollection, getEntry, render } from 'astro:content';
import { getCollection, getEntry, render } from 'vesper:content';
---

In a build, vesper:content is Astro's own module, except that it leaves out the entries that aren't on the site: one a collection's schedule keeps off it at the build's time, and a draft (draft: true) in a collection whose schema has a true-or-false draft field. A page that reads astro:content directly gets no filtering, and the build warns when it builds a page for one of those entries.

Next steps

  • Publish your edits, yourself or from the deployed site.
  • See how fields in your schema become controls.

This page as Markdown, for AI tools.