verso-cms 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -7,41 +7,22 @@
7
7
 
8
8
  <h1 align="center">Verso</h1>
9
9
 
10
- <p align="center"><strong>The page is the editor.</strong><br>
11
- A repo-first CMS for <a href="https://elevate-docs.pages.dev">Elevate</a>. Your site lives in a git repository as plain files.<br>
12
- You open it in the browser, click the real page to change it, and press Publish.</p>
10
+ <p align="center"><strong>The page is the editor.</strong></p>
13
11
 
14
- ![Editing the headline of the Verso website in place, with the editor's bar at the bottom](https://raw.githubusercontent.com/DesignInTheBlack/verso/main/docs/screenshots/editor.png)
12
+ <p align="center">Build a website by clicking on it. Your design stays consistent,<br>
13
+ your content stays organised, and every change is a plain file in git.</p>
15
14
 
16
- There's no admin screen and no separate preview. Every word, picture and block is edited where it sits on the real page, styled by the site's real CSS. What you change is saved as files: `page.json` for a page's fields, an `.html` file for each block of rich text, the images beside them. Publishing is a git commit with a message that says what changed, so the site's whole history is the repository's history.
17
-
18
- ## Build blocks by clicking
19
-
20
- **Build a block** makes or restyles a block by picking from the site's own design: spacing, colour, type and layout, for each screen size. Changes show the moment you pick them. Verso edits only the classes and elements it touches, so a block built visually can be refined by hand, and the reverse.
21
-
22
- ![The block builder: the Hero block on the left, its elements and the things you can add on the right](https://raw.githubusercontent.com/DesignInTheBlack/verso/main/docs/screenshots/builder.png)
23
-
24
- ## A brand book you can edit
25
-
26
- **Design** opens the site's colours, typefaces, type sizes, text styles, spacing, effects and screen sizes as a brand book, set in the site's own fonts. Pick anything to change it, and every page that uses it follows. Tuck the book beside the page to watch the site change as you try a colour.
27
-
28
- <table>
29
- <tr>
30
- <td><img src="https://raw.githubusercontent.com/DesignInTheBlack/verso/main/docs/screenshots/design.png" alt="The Design brand book's cover: the site's name in its own font, over its palette"></td>
31
- <td><img src="https://raw.githubusercontent.com/DesignInTheBlack/verso/main/docs/screenshots/design-typefaces.png" alt="The Typefaces chapter: each of the site's fonts as a specimen"></td>
32
- </tr>
33
- </table>
34
-
35
- ## The whole site at once
15
+ <p align="center">
16
+ <a href="https://www.npmjs.com/package/verso-cms"><img src="https://img.shields.io/npm/v/verso-cms?label=verso-cms&color=FF4F2B" alt="verso-cms on npm"></a>
17
+ <a href="https://www.npmjs.com/package/elevate-framework"><img src="https://img.shields.io/npm/v/elevate-framework?label=elevate-framework&color=1F3329" alt="elevate-framework on npm"></a>
18
+ <a href="https://github.com/DesignInTheBlack/verso/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-1F3329" alt="MIT license"></a>
19
+ </p>
36
20
 
37
- **Site view** shows every page as an outline or as a map. Drag a page to reorder it or put it inside another; its folder moves, its address follows, and links to it are rewritten. Pick a page to retitle it, change its address, duplicate it, make it a draft or delete it.
21
+ <p align="center"><a href="https://verso-docs.creative-cd9.workers.dev"><strong>Website and docs</strong></a> · <a href="https://verso-docs.creative-cd9.workers.dev/docs/start/install/">Get started</a> · <a href="https://verso-docs.creative-cd9.workers.dev/llms.txt">For AI assistants</a></p>
38
22
 
39
- <table>
40
- <tr>
41
- <td><img src="https://raw.githubusercontent.com/DesignInTheBlack/verso/main/docs/screenshots/site-view.png" alt="Site view as an outline, with the Field notes page picked"></td>
42
- <td><img src="https://raw.githubusercontent.com/DesignInTheBlack/verso/main/docs/screenshots/site-map.png" alt="Site view as a map: the home page and the pages beneath it"></td>
43
- </tr>
44
- </table>
23
+ <p align="center">
24
+ <img src="https://raw.githubusercontent.com/DesignInTheBlack/verso/main/docs/screenshots/hero.png" alt="Editing a page's headline in place, with Verso's bar at the bottom of the page">
25
+ </p>
45
26
 
46
27
  ## Start a site
47
28
 
@@ -53,237 +34,136 @@ cd my-site
53
34
  npm run dev
54
35
  ```
55
36
 
56
- The first command makes a working, styled site, installs Verso and [Elevate](https://www.npmjs.com/package/elevate-framework) into it from npm, and saves a first restore point. Add `--blank` for a home page, a 404 page and three plain blocks, with no starter design. `npm run dev` opens it in your browser, ready to edit.
37
+ Your site opens in the browser with the editor on it. Click any words to change them.
57
38
 
58
- Connect the folder to a GitHub repository and a static host (Cloudflare Pages or Netlify, build command `npm run build`, output `dist`), and every Publish updates the live site.
39
+ Add `--blank` to start from an empty site instead of the example.
59
40
 
60
- <details>
61
- <summary>On Windows</summary>
41
+ <br>
62
42
 
63
- If PowerShell says "running scripts is disabled on this system", run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` once, or type `npx.cmd` and `npm.cmd` in place of `npx` and `npm`. To use another port with `npm start` in PowerShell: `$env:PORT=3000; npm start`.
64
- </details>
43
+ ## Build the whole site in the browser
65
44
 
66
- ## A site in a box
45
+ Start from a blank site and make everything it needs without opening a file: page types, the blocks pages are built from, the design, a blog. New pages start from a page type you pick by its preview.
67
46
 
68
- A site can also run as one program that serves the pages and the editor at the same address, so the people it belongs to can edit it from any browser:
69
-
70
- ```bash
71
- npm start
72
- ```
47
+ Everything Verso makes is plain HTML in your repository. You can open any of it in your own editor, change it by hand, and keep working visually afterwards.
73
48
 
74
- - **Visitors** get the published pages, built ahead of time and served as files.
75
- - **People sign in at `/edit`** and get the editor on the site's own address. The first start writes a link that makes the first owner; owners invite everyone else from **People** in the bar, with a link that works once.
76
- - **Owners and editors:** editors change words, pictures, blocks and pages, and publish. Owners can also change the design, build blocks and manage people.
77
- - **Several people at once:** you see who else is on your page, and their saved changes appear on yours without interrupting your typing.
78
- - **Publish is live in about a second**, saved as a restore point under the publisher's name. Unpublished work is never shown to visitors, even after a restart.
79
- - **No repository needed:** the history lives in the box. If the folder has a git remote, every publish is copied there.
80
-
81
- It runs anywhere that runs a program and keeps a disk. Set `VERSO_DATA` to a folder that survives restarts and the site moves onto it; new sites come with a `Dockerfile` that does this. `npx verso owner` writes a new owner's link if everyone is locked out. The same folder still builds to static files with `npm run build`.
82
-
83
- ## Editing
84
-
85
- - **Click any text to edit it.** Press Enter or click away when you're done.
86
- - **Rich text** edits in place too. A small toolbar shows only the tools that field allows.
87
- - **Images:** click one to replace it, remove it or write its alt text, or drop an image file onto it. Images dropped into rich text become a figure with a caption.
88
- - **Changes save as you type.** The bar at the bottom says when they're saved.
89
- - **Undo** with Cmd+Z (Ctrl+Z), across every field on the page.
90
- - **New pages** come from the page menu: pick a template from its preview, give the page a name, and choose where it goes.
91
- - **Page settings** hold what isn't on the page: the search title and description, the date, and fields like a link's address. A page's address can be changed there, and the site's links and lists follow it. A page can be deleted there too.
92
- - **Publish** saves a restore point with a message that says what changed, like "Update Home (headline)", and pushes it. It refuses, and says why, if something would break the live site.
93
- - **Say what changed:** the first press of Publish shows what's waiting and asks for a few words. History shows them beside the date.
94
-
95
- ## Building a site in the editor
49
+ <p align="center">
50
+ <img src="https://raw.githubusercontent.com/DesignInTheBlack/verso/main/docs/screenshots/new-page.png" alt="The New page dialog, with each page type shown as a live preview">
51
+ </p>
96
52
 
97
- Everything a site needs can be made in the browser, without opening a file:
53
+ <br>
98
54
 
99
- - **Site settings:** the site's name, address, sub-folder, language and search.
100
- - **Design:** colours, fonts, sizes and spacing, how article text looks (headings, links, quotes, code), and the site's screen sizes, all from the site's tokens.
101
- - **Screen sizes:** see the whole page at a phone's width, a tablet's or any of the site's sizes, and keep editing there. In Build a block, pick a size and the preview snaps to it; what you choose applies from that size up.
102
- - **Blocks:** the starter comes with a header, footer, hero, text, features, team, latest posts and more. **Build a block** makes new ones from words: text, pictures, buttons, lists of pages (sorted, filtered, split into pages, with words for when there are none), lists of items, "show only when", counts, this page's title and tags, and text shared by every page.
103
- - **Shared header and footer:** blocks in them are the same on every page; change one anywhere.
104
- - **Page types:** make a new one from an existing type, and start new pages like the one you're on.
105
- - **Channels:** turn a folder into a journal, portfolio or anything that grows, with New post, drafts, a feed, and a page for each tag.
55
+ ## Design and building are one system
106
56
 
107
- The rest of this section is for developers who'd rather write templates by hand. Everything the editor builds is plain HTML you can open and change.
57
+ Your colours, typefaces, sizes and spacing live in one place: the design. When you build a block, those are the only choices on offer. You pick from your palette and your type scale, never from a free-for-all colour picker or a box for pixel values.
108
58
 
109
- ## Building a site by hand
59
+ Because every block draws from the same design, one change reaches the whole site. Make the accent warmer, or the headings larger, and every page that uses them follows.
110
60
 
111
- Templates are plain HTML. Styles are Elevate classes. Besides HTML, a template holds fields, lists, repeaters, conditions, references and parts.
61
+ <p align="center">
62
+ <img src="https://raw.githubusercontent.com/DesignInTheBlack/verso/main/docs/screenshots/one-system.png" alt="Left: the site's colours in the Design brand book. Right: the block builder, offering exactly those colours and type sizes for the selected headline">
63
+ </p>
112
64
 
113
- **Fields** are written where their value goes, as `name:type:modifiers`:
65
+ The design opens as a brand book, set in your site's own fonts. Tuck it beside the page to try a colour and watch the site change before you save it.
114
66
 
115
- ```html
116
- <h1 class="font:h1:bold">{{ headline:text:required }}</h1>
117
- <img src="{{ cover:image }}">
118
- <div>{{ body:rich:headings:lists:links:images }}</div>
119
- <a href="mailto:{{ email:text }}">Write to us</a>
120
- <section style="--ink: {{ ink:color }}">…</section>
121
- <div>{{ sections:blocks }}</div>
122
- ```
67
+ <p align="center">
68
+ <img src="https://raw.githubusercontent.com/DesignInTheBlack/verso/main/docs/screenshots/brand-book.png" alt="Left: the brand book's cover. Right: a colour being tried with the book tucked beside the page">
69
+ </p>
123
70
 
124
- | Type | What it holds | Modifiers |
125
- | --- | --- | --- |
126
- | `text` | One line of plain text | `required` |
127
- | `rich` | Formatted text. Needs an element to itself | `required`, plus any of `headings`, `lists`, `links`, `images`, `tables`, `quotes`, `callouts`, `embeds` (YouTube and Vimeo videos) and `code` (code blocks and inline code). Paragraphs, bold and italic are always on |
128
- | `image` | An image and its alt text. Goes in an attribute, like `src` | `required` |
129
- | `color` | One of the site's colours, chosen from swatches. Renders its CSS value | `required` |
130
- | `blocks` | A slot for blocks. Needs an element to itself | the names of the blocks it takes |
71
+ <br>
131
72
 
132
- A field inside a tag, like `href` above, isn't clickable, so it appears in Page settings instead. An empty colour in a `style` attribute renders `initial`, so `var(--ink, #000)` falls back to its default.
73
+ ## Content that stays organised
133
74
 
134
- **Lists** repeat their contents for each page in a folder, with `{{ else }}` for when there are none:
75
+ - **Pages are folders.** `content/about/` is `/about/`. Its words and images live inside it and move with it.
76
+ - **Page types** give similar pages the same layout and the same fields to fill in.
77
+ - **Channels** turn a folder into a blog, a changelog or a portfolio: new posts, drafts, search, and an RSS feed.
78
+ - **Tags** group pages across folders, and each tag can have its own page.
79
+ - **Shared sections,** like the header and footer, are the same on every page. Change one anywhere and it changes everywhere.
80
+ - **Site view** shows every page as an outline or a map. Drag a page to move it, and its address and every link to it follow.
135
81
 
136
- ```html
137
- {{ each:journal:newest:10 }}
138
- <a href="{{ item.url }}">{{ item.title }}</a>
139
- <time datetime="{{ item.date-iso }}">{{ item.date:short }}</time>
140
- {{ else }}
141
- <p>Nothing here yet.</p>
142
- {{ /each }}
143
- ```
82
+ <p align="center">
83
+ <img src="https://raw.githubusercontent.com/DesignInTheBlack/verso/main/docs/screenshots/site-view.png" alt="Left: Site view as a map. Right: Site view as an outline, with one page's details">
84
+ </p>
144
85
 
145
- After the folder, add any of these, in any order:
86
+ <p align="center">
87
+ <img width="720" src="https://raw.githubusercontent.com/DesignInTheBlack/verso/main/docs/screenshots/channels.png" alt="The Channels panel, listing a changelog's posts with search and a drafts filter">
88
+ </p>
146
89
 
147
- | Write | To |
148
- | --- | --- |
149
- | `newest`, `oldest`, `a-z`, `z-a`, `order` | Sort. `newest` is the default; `order` is the order set in the site view |
150
- | `10` | Show 10 at most |
151
- | `skip-1` | Leave out the first one |
152
- | `others` | Leave out the page the list is on |
153
- | `10:paged` | Show 10 per page, and make `/journal/page/2/`, `/journal/page/3/`… |
154
- | `tagged-design` | Only pages tagged Design |
155
- | `has-cover`, `no-cover` | Only pages whose cover is filled in, or empty |
156
- | `kind=essay`, `kind!=essay` | Only pages whose kind is, or isn't, essay |
90
+ <br>
157
91
 
158
- Instead of a folder, a list can show `children` (the pages inside this one), `siblings` (the pages beside it), `item` (inside another list: the pages inside each item), `tags` (this page's tags) or `item.tags`. Lists go three deep.
92
+ ## Built on Elevate
159
93
 
160
- Inside, `{{ item.url }}`, `item.title`, `item.description`, `item.date`, `item.date-iso`, `item.label` and `item.tags` show that page's settings, and `{{ item.cover }}` shows any of its fields; an image brings its alt text. A reference can take a format: dates take `long` (the default), `short`, `numeric`, `month`, `year` or `iso`, and text takes `words-25` or `chars-140`.
94
+ Verso's styles are written in [Elevate](https://elevate-docs.pages.dev), a CSS framework built on design tokens. It's the reason the editor can keep your design consistent.
161
95
 
162
- **Pages of a list:** with `:paged`, `{{ paging.next }}` and `{{ paging.previous }}` are the addresses of the next and previous pages (empty at the ends), and `{{ paging.number }}` and `{{ paging.total }}` say where you are:
96
+ **Classes read like design decisions.** Each class names a property and the values from your design, in any order:
163
97
 
164
98
  ```html
165
- {{ if:paging.next }}<a href="{{ paging.next }}">Older posts</a>{{ /if }}
99
+ <section class="contain col gap:d8 pd-t:c1 /md/ pd-t:c5">
100
+ <h1 class="font:display:regular:tight text:ink">{{ headline:text }}</h1>
101
+ <a class="pd:d3:d5 bg-color:ink text:paper @hover:[bg-color:accent]">Get started</a>
102
+ </section>
166
103
  ```
167
104
 
168
- **Counts:** `{{ count:journal }}`, or `{{ count:journal:tagged-design }}`, with the same filters as a list.
169
-
170
- **Conditions** show their contents only when a field has something in it, and `{{ else }}` when it doesn't: `{{ if:cover }}…{{ else }}…{{ /if }}`. `{{ if:!cover }}` means "when cover is empty", and `{{ if:kind=essay }}` or `{{ if:kind!=essay }}` compares. They check this page's fields, `item.` inside a list, `page.` settings, `parent.` fields and `paging.`. In the editor, the part with this page's own fields stays visible, so an empty field can still be filled in.
105
+ **Only your design is allowed.** Every value has to be one of your tokens. A typo, or a colour that isn't in your palette, stops the build with the file and line, so it never reaches the live site:
171
106
 
172
- **Tags:** any page can have tags, set in Page settings and kept in `page.json` as `"tags": ["Design", "Process"]`. To give a folder's tags their own pages, make a page with `"tags-of": "journal"` in its `page.json`, like `content/topics/`, beside the folder rather than inside it. It becomes the list of every tag, and Verso makes a page for each tag beneath it (`/topics/design/`), all with that page's template. In it, `{{ page.tag }}` is the tag (empty on the list itself), `{{ each:tagged }}` lists the pages with that tag, and `{{ each:all-tags }}` lists every tag with `{{ item.count }}`, sorted `a-z` or by `most` used:
173
-
174
- ```html
175
- <h1>{{ if:page.tag }}Posts about {{ page.tag }}{{ else }}Topics{{ /if }}</h1>
176
- {{ if:page.tag }}
177
- {{ each:tagged }}<a href="{{ item.url }}">{{ item.title }}</a>{{ /each }}
178
- {{ else }}
179
- {{ each:all-tags:most }}<a href="{{ item.url }}">{{ item.title }} ({{ item.count }})</a>{{ /each }}
180
- {{ /if }}
181
107
  ```
182
-
183
- A post's own tags link to those pages: `{{ each:tags }}<a href="{{ item.url }}">{{ item.title }}</a>{{ /each }}`.
184
-
185
- **Repeaters** are lists of items edited right on the page, like a team or questions and answers. Each item is one element, and its fields are its own:
186
-
187
- ```html
188
- <ul>
189
- {{ list:team }}
190
- <li>
191
- <img src="{{ photo:image }}">
192
- <h3>{{ name:text }}</h3>
193
- <p>{{ role:text }}</p>
194
- </li>
195
- {{ /list }}
196
- </ul>
108
+ × blocks/hero.html, line 1
109
+ The class "bg-color:brand-red" isn't valid. Unable to determine modifier type for "brand-red"
110
+ Change or remove that class in the template.
197
111
  ```
198
112
 
199
- The list needs an element to itself. In the editor, items are added, moved, duplicated and removed in place.
113
+ **Screen sizes are part of the class.** Everything after `/md/` applies from tablet width up. Layouts start on the smallest screens and change as the screen grows.
200
114
 
201
- **Shared fields and block areas** are the same on every page, like a footer line, a phone number, or a whole header: `{{ site.phone:text }}`, `{{ site.notice:rich }}` or `{{ site.header:blocks }}`. Edit one on any page and every page changes. They're kept in `content/site.json`; images in a shared block area are kept in `content/` itself, as `/logo.png`.
115
+ **Only the CSS you use is generated.** Elevate reads your templates and writes a stylesheet with just those classes.
202
116
 
203
- **Page references** show this page's settings anywhere, as `{{ page.title }}`, `page.date`, `page.date-iso`, `page.description`, `page.url`, `page.label`, `page.tags` and `page.tag`, and the page it sits inside as `{{ parent.title }}` or any of its fields.
117
+ **The editor uses the same tokens.** The colours in the block builder, the sizes in the type picker and the swatches in the brand book all come from the same design files that Elevate compiles.
204
118
 
205
- **Parts** share HTML between templates and blocks. `{{ part:header }}` is replaced by `parts/header.html`, so a header or footer lives in one file. A part can take values, so it works like a component:
119
+ <br>
206
120
 
207
- ```html
208
- {{ each:journal }}
209
- {{ part:card title=item.title link=item.url label="Read more" }}
210
- {{ /each }}
211
- ```
212
-
213
- In `parts/card.html`, `{{ part.title }}` shows the value, and `{{ if:part.title }}` checks it. A value is a reference (`item.`, `page.`, `parent.`, `paging.`) or "quoted text". A part can hold anything a template can, except another part; a field in a part belongs to each page, like any field. Errors in a part name the part's file and line.
214
-
215
- **Scripts** go in `public/`, loaded with `<script type="module" src="/js/site.js">`. The editor loads the real page, so they run while editing too; `<html>` carries `data-verso-editing` there, so a script can leave editable text alone. For Elevate to compile classes a script adds, add its folder to `Watch` in `elevate/config/elevate.ts` and write each class list in full.
216
-
217
- **Extra files:** with `"index": true` in `verso.json`, the build writes `pages.json`, every live page with its title, tags, headings and text, ready for search. With `"url"`, it writes `sitemap.xml` and an RSS feed for each channel at `/<folder>/feed.xml`, linked from that channel's pages. A page at `content/404/` also becomes `404.html`. The editor serves these too, so scripts that read them work while editing.
121
+ ## How it's stored
218
122
 
219
- **A site in a sub-folder:** with `"base": "/blog"` in `verso.json`, the build puts `/blog` in front of every address that starts at the root, in links, images and scripts (code samples are left alone). `<html>` carries `data-base="/blog"`, so a script can build addresses too.
123
+ A Verso site is a folder of ordinary files. The editor reads and writes them, and publishing commits them to git, so your site's history is the repository's history.
220
124
 
221
- ## Where things are kept
222
-
223
- | To add | Do this |
224
- | --- | --- |
225
- | A field | Type it in a template |
226
- | A template | Add an HTML file to `templates/` |
227
- | HTML shared by templates or blocks | Add it to `parts/` and write `{{ part:name }}` |
228
- | A page | Use New page in the editor, or add a folder to `content/` with a `page.json` that names its template. The folder path is the address: `content/about/` is `/about/` |
229
- | A colour, font or size | Use the Design panel, which keeps them in `elevate/design/tokens.json` (`site.ts` is for extras written by hand) |
230
- | A starting layout for a page type | Set a page up, then **Start new pages like this one** in Page settings. It's kept in `templates/<type>.layout.json` |
231
-
232
- - `page.json` holds a page's settings (template, title, description, date) and its text and image fields.
233
- - Each rich text field is its own file next to it, like `body.html`: clean HTML with no classes.
234
- - Images are kept in the page's own folder, so they move with the page.
235
- - The look of rich text comes from `"rich"` in `verso.json`, which gives each element its Elevate classes. Elevate checks and compiles these like any other class:
236
-
237
- ```json
238
- {
239
- "name": "Northlight",
240
- "rich": { "p": "text:ink-2:relaxed", "h2": "font:h4:semibold", "a": "text:accent" }
241
- }
125
+ ```
126
+ my-site/
127
+ ├── content/ pages: one folder each, holding its words and images
128
+ ├── templates/ page types, as HTML
129
+ ├── blocks/ blocks, as HTML
130
+ ├── parts/ HTML shared by templates and blocks
131
+ ├── elevate/ the design: colours, fonts, sizes, spacing
132
+ └── verso.json site settings, text styles and channels
242
133
  ```
243
134
 
244
- `npm run build` writes the finished site to `dist/`, with each page's images beside it and every image sized. Wide JPEGs and PNGs also get smaller copies (640, 1024 and 1600 pixels wide) with a `srcset`, so phones download less; the copies are kept in `.verso-cache/` so rebuilds are quick. Any mistake (a bad class, an unknown field type, an empty required field) stops the build and names the file and line. Content left over from a field a template no longer has is only a warning.
135
+ <br>
245
136
 
246
- ## In the editor
137
+ ## Put it online
247
138
 
248
- - **Blocks:** templates and blocks declare block areas, like `{{ sections:blocks }}` or `{{ items:blocks:card }}`. The Blocks library shows every block rendered live; drag one onto the page and only the block areas that accept it light up. Blocks nest, and each has a handle to move, duplicate or remove it.
249
- - **Site view:** every page, full screen, as an outline or a map. Drag a page to reorder it, or onto another to put it inside; the folder moves, the address follows, and links to it are updated. From the keyboard, Alt and the arrows move a page, Tab puts it inside the page above and Shift+Tab takes it out. The page you pick shows its preview, title, address, page type and where it sits, with Open, Page inside, Duplicate (a draft copy beside it), Make live or Back to draft, and Delete. Any page can be a draft, kept out of the live site until it's ready.
250
- - **History:** a timeline of every publish. Preview a page as it was, and restore it as an unpublished change. If two people change the same page, Verso shows both versions side by side and asks which to keep.
251
- - **Build a block:** make or restyle a block by clicking: spacing, colour, type, layout and more, chosen only from the design tokens, per screen size. The block is shown the way it sits on a page, inside the same elements as its block area. Picking a size shows the block at that width; a dashed choice is one it gets from a smaller size, and a dot on a size means the selected element changes there. Verso edits only the classes and elements it touches, so hand-written code is never damaged, and a block built visually can be refined in code. The bin deletes a block; one that's in use asks first, then comes off every page.
252
- - **Design:** the site's tokens as a full-screen brand book: a cover set in the site's own heading font and colours, then colour as swatch strips, typefaces as specimens, type sizes as a typeset scale, text styles, spacing, effects and screen sizes. Pick anything to open it in a drawer beside the book, or tuck the book beside the page to see the site change as you work. Add colours, sizes, fonts, spacing, shadows and gradients by looking at them. Make a nine-step colour ramp from one colour with its contrast shown, write fluid sizes from a phone and a wide-screen size, and drop in font files: Verso reads each font's name, weight and style from the file, and a variable font keeps every weight. Renaming or removing a token shows where it's used first, and can rename it everywhere. Site tokens live in `elevate/design/tokens.json`. **Text styles** style article text (paragraphs, headings, links, quotes, code, tables), saved as `"rich"` in `verso.json`. **Screens** names, moves, adds and removes the site's screen sizes (Elevate's breakpoints): widths are kept in `tokens.json` as `"BreakPointToken"` and names in `verso.json` as `"screens"`. Removing one that's in use asks first, then removes the styles set for it. Needs Elevate 1.3 or later.
253
- - **Screen sizes:** the bar's Screen sizes button shows the page at a phone's width or any of the site's sizes, scaled to fit. You can edit there as usual; the page underneath catches up when you press Done. A class list written by hand with its size markers out of order gets a note at the top right, with the file and line.
139
+ **As a static site.** Push the folder to GitHub and connect it to Cloudflare Pages or Netlify, with build command `npm run build` and output folder `dist`. Every Publish updates the live site.
254
140
 
255
- ### Channels
141
+ **As a box.** `npm start` runs the site and its editor together at one address. You and the people you invite sign in at `/edit` and edit from any browser, and publishing is live in about a second. New sites include a Dockerfile. [More about boxes](https://github.com/DesignInTheBlack/verso/blob/main/docs/box.md).
256
142
 
257
- A channel is a folder of posts: a journal, notes, case studies. List it in `verso.json` and the editor gets a Channels panel for it.
143
+ <br>
258
144
 
259
- ```json
260
- "channels": {
261
- "journal": { "label": "Journal", "template": "post", "item": "post" }
262
- }
263
- ```
145
+ ## Guides
264
146
 
265
- The key is the folder inside `content/` (`docs/guides` works too). `template` is the template every new post uses. `label` is what the panel calls the channel (it defaults to the folder's name), and `item` is what one post is called (it defaults to "entry").
147
+ The full documentation is on [the Verso website](https://verso-docs.creative-cd9.workers.dev/docs/), which is itself a Verso site. These guides cover the same ground in brief:
266
148
 
267
- Open Channels from the bar, the page menu on phones, or the command palette ("New post in Journal", "Open a post in Journal…"). The panel lists the posts newest first, with search and a Drafts/Live filter. **New post** asks only for a title: the post is made with the channel's template, dated today, as a draft, and opens ready to write. Each post can be duplicated (as a draft), made a draft or taken out of drafts, or deleted. Deleting removes the post's folder; if it was ever published, it's still in History.
149
+ | | |
150
+ | --- | --- |
151
+ | **[Using the editor](https://github.com/DesignInTheBlack/verso/blob/main/docs/editor.md)** | Pages, blocks, the block builder, Design, Site view, channels, history and publishing |
152
+ | **[Writing templates](https://github.com/DesignInTheBlack/verso/blob/main/docs/templates.md)** | Fields, lists of pages, conditions, repeaters, tags, parts and scripts |
153
+ | **[Where things are kept](https://github.com/DesignInTheBlack/verso/blob/main/docs/files.md)** | Which file holds what, and what the build produces |
154
+ | **[Running a site as a box](https://github.com/DesignInTheBlack/verso/blob/main/docs/box.md)** | Sign-in, roles, working together and hosting |
155
+ | **[Working on Verso](https://github.com/DesignInTheBlack/verso/blob/main/docs/developing.md)** | Setting up, finding your way around the code, and running the tests |
268
156
 
269
- If a channel's folder or template doesn't exist, the panel says which and how to fix it.
157
+ ### For AI assistants
270
158
 
271
- ## Status
159
+ Point an assistant at [llms.txt](https://verso-docs.creative-cd9.workers.dev/llms.txt) before it builds a Verso site. It explains the files, the template language, the mistakes the build catches and how to fix them, and it links to [Elevate's own guide](https://elevate-docs.pages.dev/llms.txt). Everything in one file: [llms-full.txt](https://verso-docs.creative-cd9.workers.dev/llms-full.txt).
272
160
 
273
- Every part of the plan is built: one-command sites, click-to-edit with autosave and Publish; rich text with images, tables and video embeds; page lists, new pages and undo; blocks, components, the site view, drafts, history and side-by-side conflicts; the visual block builder; visual design tokens; a command palette (Ctrl+K or ⌘K); channels for posts; and shared template parts. Images are resized at build.
161
+ <br>
274
162
 
275
- Still to do before calling it finished: try it on macOS and Windows, in Safari and Firefox, and on more real sites.
163
+ ## Status
276
164
 
277
- ## Developing Verso
165
+ Verso is at version 0.1. It runs [its own website](https://verso-docs.creative-cd9.workers.dev) and has a full test suite, but it hasn't yet been tried in every browser and on every system. If something breaks, please [open an issue](https://github.com/DesignInTheBlack/verso/issues).
278
166
 
279
- ```bash
280
- git clone https://github.com/DesignInTheBlack/verso.git
281
- cd verso
282
- npm install
283
- npm test
284
- ```
167
+ ## License
285
168
 
286
- - `npm test` runs the tests.
287
- - To try your changes on a site, run `node path/to/verso/bin/verso.js` inside it, or `npm pack` here and run `npx -y --package=./verso-cms-0.1.2.tgz verso new my-site` beside the `.tgz`: the new site gets its own copy in `vendor/`.
288
- - The box (`verso serve`) is `src/box.js` (the published pages, the sign-in pages and the check every request passes) and `src/people.js` (people, passwords, sessions and links). The sign-in pages are in `editor/door.js`, so their classes compile with the rest of the interface.
289
- - `npm run build:ui` compiles the editor's own styles and bundles the rich text editor (`editor/rich.src.js`, built on ProseMirror). The editor is built with Elevate: its classes are in `editor/editor.js`, written as `ui("…")`, and its tokens are in `elevate/design/verso.ts`.
169
+ [MIT](https://github.com/DesignInTheBlack/verso/blob/main/LICENSE)
@@ -287,17 +287,36 @@ export function init(verso) {
287
287
  return n ? `Used in ${n} place${n === 1 ? '' : 's'}` : 'Not used yet';
288
288
  };
289
289
 
290
+ // A colour can be a CSS variable, like var(--paper), so a site's own CSS can
291
+ // change it (one value per theme, say). The panel shows what it is right now
292
+ // and leaves the variable alone unless someone chooses a fixed colour.
293
+ const variableOf = (value) => (/^var\(\s*(--[\w-]+)/.exec(String(value || '')) || [])[1] || null;
294
+ const hexNow = (value) => {
295
+ const probe = document.createElement('i');
296
+ probe.style.color = value;
297
+ document.body.append(probe);
298
+ const rgb = getComputedStyle(probe).color.match(/\d+(\.\d+)?/g) || [];
299
+ probe.remove();
300
+ return rgb.length >= 3 ? '#' + rgb.slice(0, 3).map((n) => Math.round(Number(n)).toString(16).padStart(2, '0')).join('').toUpperCase() : null;
301
+ };
302
+ const tidyColour = (value) => (/^#[0-9a-f]{3,8}$/i.test(value) ? value.toUpperCase() : value);
303
+
290
304
  const detail = (type, name, force = false) => {
291
305
  if (!force && !state.docked) return '';
292
306
  if (!state.detail || state.detail.type !== type || state.detail.name !== name) return '';
293
307
  const used = state.detail.usage;
294
308
  const value = state.data.own[type][name];
295
- const hex = /^#[0-9a-f]{6}$/i.test(value) ? value : null;
296
309
  const isColour = type === 'ColorToken';
310
+ const variable = isColour ? variableOf(value) : null;
311
+ const hex = /^#[0-9a-f]{6}$/i.test(value) ? value : (variable || isColour ? hexNow(value) : null);
297
312
  const valueEditor = isColour
298
- ? `<div class="${ui("row:y-center gap:d3")}">
313
+ ? `${variable ? `<div data-variable class="${ui("col gap:d2")}">
314
+ <p class="${ui("font:tiny text:ink-3")}">This colour comes from the CSS variable <code class="${ui("font:mono:tiny text:ink")}">${esc(variable)}</code>, so the site's own CSS can change it, for example once per theme. Here it's ${esc(hex || 'not set')}.</p>
315
+ ${button('data-fix-colour', 'Use a fixed colour instead')}
316
+ </div>` : ''}
317
+ <div data-colour-picker class="${ui("row:y-center gap:d3")}"${variable ? ' hidden' : ''}>
299
318
  <input type="color" data-edit-colour value="${esc(hex || '#000000')}" aria-label="Colour" class="${ui("w:c1 h:d11 pd:d0 bd:round-d3 bd:width-px:solid:line bg-color:paper cursor:pointer child:no-shrink")}">
300
- <p class="${ui("font:tiny text:ink-3")}">Drag to try colours. The page shows each one as you go, and nothing changes until you save.</p>
319
+ <p class="${ui("font:tiny text:ink-3")}">Drag to try colours. The page shows each one as you go, and nothing changes until you save.${variable ? ` Saving replaces ${esc(variable)} with this colour.` : ''}</p>
301
320
  </div>
302
321
  <details class="${ui("col gap:d1")}"><summary class="${ui("font:tiny text:mist cursor:pointer")}">The CSS</summary>
303
322
  <div class="${ui("row:y-center gap:d2 pd-t:d1")}">${input(`data-edit-value value="${esc(value)}" aria-label="CSS value" spellcheck="false"`)}</div>
@@ -1040,11 +1059,20 @@ export function init(verso) {
1040
1059
  if (from && to.toUpperCase() !== from.toUpperCase()) previewColour(from, to); else endPreview();
1041
1060
  };
1042
1061
  pickColour?.addEventListener('input', () => { editValue.value = pickColour.value.toUpperCase(); tryColour(pickColour.value); });
1062
+ q('[data-fix-colour]')?.addEventListener('click', () => {
1063
+ q('[data-variable]')?.setAttribute('hidden', '');
1064
+ q('[data-colour-picker]')?.removeAttribute('hidden');
1065
+ pickColour?.focus();
1066
+ });
1043
1067
  q('[data-undo-value]')?.addEventListener('click', () => {
1044
1068
  const from = state.data.own.ColorToken?.[state.detail?.name];
1045
1069
  if (!from) return;
1046
1070
  editValue.value = from;
1047
1071
  if (/^#[0-9a-f]{6}$/i.test(from)) pickColour.value = from;
1072
+ if (variableOf(from)) {
1073
+ q('[data-variable]')?.removeAttribute('hidden');
1074
+ q('[data-colour-picker]')?.setAttribute('hidden', '');
1075
+ }
1048
1076
  tryColour(from);
1049
1077
  });
1050
1078
  editValue?.addEventListener('input', () => { if (pickColour && /^#[0-9a-f]{6}$/i.test(editValue.value.trim())) pickColour.value = editValue.value.trim(); });
@@ -1068,7 +1096,8 @@ export function init(verso) {
1068
1096
  const value = editValue.value.trim();
1069
1097
  if (!value || value === state.data.own[type][name]) return;
1070
1098
  const keep = { ...state.detail };
1071
- const out = await save('/__verso/tokens', { type, name, value: type === 'ColorToken' ? value.toUpperCase() : value }, `${name} is now ${type === 'ColorToken' ? value.toUpperCase() : value}.`);
1099
+ const stored = type === 'ColorToken' ? tidyColour(value) : value;
1100
+ const out = await save('/__verso/tokens', { type, name, value: stored }, `${name} is now ${stored}.`);
1072
1101
  if (out) { state.detail = keep; render(); } else endPreview();
1073
1102
  };
1074
1103
  q('[data-do-value]')?.addEventListener('click', saveValue);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "verso-cms",
3
- "version": "0.1.2",
3
+ "version": "0.1.3",
4
4
  "description": "A repo-first CMS for Elevate. Edit the real page in your browser, then publish with git.",
5
5
  "scripts": {
6
6
  "build:ui": "tsx elevate/core/index.ts build && npm run build:rich",
@@ -64,7 +64,7 @@
64
64
  "type": "git",
65
65
  "url": "git+https://github.com/DesignInTheBlack/verso.git"
66
66
  },
67
- "homepage": "https://github.com/DesignInTheBlack/verso#readme",
67
+ "homepage": "https://verso-docs.creative-cd9.workers.dev",
68
68
  "bugs": {
69
69
  "url": "https://github.com/DesignInTheBlack/verso/issues"
70
70
  }
@@ -440,7 +440,7 @@ export async function setup(ctx) {
440
440
  checkName(type, name, d, { override: body.override === true });
441
441
  if (!value) throw new VersoError('Give the token a value.');
442
442
  if (/[;{}<>]/.test(value)) throw new VersoError('That value has characters CSS values can\'t contain here: ; { } < >');
443
- if (type === 'ColorToken' && !parseHex(value) && !/^(rgb|hsl|oklch|oklab|color)\(/i.test(value)) throw new VersoError(`"${value}" isn't a colour. Use a hex value like #B8471F.`);
443
+ if (type === 'ColorToken' && !parseHex(value) && !/^(rgb|hsl|oklch|oklab|color|var)\(/i.test(value)) throw new VersoError(`"${value}" isn't a colour. Use a hex value like #B8471F, or a CSS variable like var(--paper).`);
444
444
  tokens[type] = { ...(tokens[type] || {}), [name]: value };
445
445
  ctx.sendJSON(res, 200, { ok: true, cssProblem: await writeTokens(tokens) });
446
446
  return true;
package/src/scaffold.js CHANGED
@@ -120,7 +120,7 @@ export async function createSite(folder, { install = true, blank = false, log =
120
120
  type: 'module',
121
121
  scripts: { dev: 'verso', build: 'verso build', start: 'verso serve' },
122
122
  dependencies: {
123
- 'elevate-framework': spec('elevate-framework') || '^1.3.1',
123
+ 'elevate-framework': spec('elevate-framework') || '^1.3.2',
124
124
  'verso-cms': process.env.VERSO_SPEC || spec('verso-cms') || `^${ownPackage.version}`,
125
125
  },
126
126
  };