Reference

Commands

Verso has three commands. A site made with verso new gets npm scripts for the two you use every day, so you rarely type verso yourself.

Commandnpm scriptWhat it does
verso new <folder>Makes a new site in that folder
versonpm run devOpens the editor for the site
verso buildnpm run buildBuilds the finished site into dist/
verso servenpm startRuns the site for the internet: the published pages for visitors, and the editor for people who sign in at /edit
verso ownerWrites a link that makes one new owner of a served site

verso --help (or verso help) lists the commands and options, and verso --version prints Verso's version. An option Verso doesn't know stops with “--… isn't a Verso option.”

verso new

npx verso-cms new my-site

Makes a working, styled site in a new folder:

  1. Copies the starter site: templates, blocks, a few pages, the rich text classes and the starter’s Elevate settings. It writes verso.json with a name made from the folder, like “Field Notes” for field-notes, and puts that name in the shared header and footer.
  2. Writes package.json and installs Verso and Elevate with npm.
  3. Sets up Elevate’s compiler in elevate/, keeping the starter’s settings.
  4. Runs git init on a main branch and saves a first restore point, “Start a Verso site”.

The folder must be new or empty, so nothing is overwritten. If git isn’t installed, or doesn’t know your name yet, the site is still made and Verso says what to do before you publish.

FlagEffect
--blankStarts with almost nothing: a home page, a 404 page, one page template and three blocks (a header, a footer and a text block), in plain black and white. Use it when you're bringing your own design and would only delete the starter's
--no-installCopies the files and makes the first commit, without running npm. Run npm install in the folder before editing. Verso sets up Elevate’s compiler the first time verso or verso build runs

verso (the editor)

npm run dev
npm run dev -- --port=5000 --no-open

Starts the editor at http://localhost:4321 and opens it in your browser. It finds the site by looking for verso.json in the current folder or any folder above it. verso edit does the same thing. If Elevate’s compiler isn’t in elevate/ yet, Verso sets it up first.

FlagEffect
--port=<number>Uses another port. The default is 4321. --port 5000 works too. If the port is busy, Verso uses the next free one and says so
--no-openDoesn’t open a browser

The editor answers only this computer: requests from other hosts are refused. It watches the site’s files, so a change made in your code editor shows up on the page straight away. When it starts, it brings in the latest published version from the remote, unless you have unpublished changes. Press Ctrl C to stop it.

verso build

npm run build

Checks the whole site, then writes it to dist/, replacing what was there:

  • every live page as index.html in its own folder, with its images beside it;
  • elevate.css, compiled from every class the site uses;
  • everything in public/, copied as it is;
  • smaller copies of wide images, with a srcset (kept in .verso-cache/ so rebuilds are quick);
  • a page for each tag of a tags page, and the numbered pages of any list split into pages;
  • 404.html, sitemap.xml, pages.json and an RSS feed for each channel when the site asks for them (see Search, sitemaps and 404s).

Drafts are left out. Any problem stops the build with a message that names the file and line, and the command exits with an error, so a host’s build fails rather than publishing a broken site. Warnings, like content left over from a field a template no longer has, are printed but don’t stop the build. Like verso, it sets up Elevate’s compiler first if it’s missing.

√ Built 42 pages, 5 tag pages and 2 more pages of lists into dist/ in 1840 ms.

verso serve

npm start

Runs the site as a box: one program that serves the published pages and, to people who sign in, the editor. It makes the folder a git repository if it isn't one, builds the published pages, and waits. When nobody can edit yet, it writes the link that makes the first owner.

Flag or settingEffect
--port=8080, or PORTThe port to listen on. Serve stops if it's taken, so a host never ends up with the site on a port it isn't watching
--data=<folder>, or VERSO_DATAA folder that's kept between restarts. The site is copied into it the first time and runs from there, so its edits, history and people survive a redeploy
--host=<address>The network address to listen on. Every address, unless you say otherwise

The list of people is kept in .verso/people.json, with each password stored as a salted hash. That folder also holds the published pages, and never goes into the site's history.

verso owner

npx verso owner

Run in a served site's folder, it writes a link like /edit/join?t=…. Opened on the site, it makes one new owner. It works once and lasts seven days. Use it if every owner is locked out.

Elevate’s commands

Elevate’s own command line is available through npm run elevate. On a Verso site you won’t need its watcher, because the editor compiles for you, but these are useful:

CommandWhat it does
npm run elevate -- buildCompiles once and exits, with an error if a class is wrong
npm run elevate -- check "<classes>"Checks a class list and names each bad class
npm run elevate -- describePrints the design system as JSON: breakpoints, tokens, rules and properties
npm run elevate -- versionPrints Elevate’s version