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.
| Command | npm script | What it does |
|---|---|---|
verso new <folder> | Makes a new site in that folder | |
verso | npm run dev | Opens the editor for the site |
verso build | npm run build | Builds the finished site into dist/ |
verso serve | npm start | Runs the site for the internet: the published pages for visitors, and the editor for people who sign in at /edit |
verso owner | Writes 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:
- Copies the starter site: templates, blocks, a few pages, the rich text classes and the starter’s Elevate settings. It writes
verso.jsonwith a name made from the folder, like “Field Notes” forfield-notes, and puts that name in the shared header and footer. - Writes
package.jsonand installs Verso and Elevate with npm. - Sets up Elevate’s compiler in
elevate/, keeping the starter’s settings. - Runs
git initon amainbranch 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.
| Flag | Effect |
|---|---|
--blank | Starts 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-install | Copies 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.
| Flag | Effect |
|---|---|
--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-open | Doesn’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.htmlin 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.jsonand 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 setting | Effect |
|---|---|
--port=8080, or PORT | The 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_DATA | A 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:
| Command | What it does |
|---|---|
npm run elevate -- build | Compiles 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 -- describe | Prints the design system as JSON: breakpoints, tokens, rules and properties |
npm run elevate -- version | Prints Elevate’s version |