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 +93 -213
- package/editor/ext-tokens.js +33 -4
- package/package.json +2 -2
- package/src/extensions/tokens.js +1 -1
- package/src/scaffold.js +1 -1
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
|
|
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
|
-
|
|
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
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-

|
|
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
|
-
|
|
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
|
-
<
|
|
40
|
-
<
|
|
41
|
-
|
|
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
|
-
|
|
37
|
+
Your site opens in the browser with the editor on it. Click any words to change them.
|
|
57
38
|
|
|
58
|
-
|
|
39
|
+
Add `--blank` to start from an empty site instead of the example.
|
|
59
40
|
|
|
60
|
-
<
|
|
61
|
-
<summary>On Windows</summary>
|
|
41
|
+
<br>
|
|
62
42
|
|
|
63
|
-
|
|
64
|
-
</details>
|
|
43
|
+
## Build the whole site in the browser
|
|
65
44
|
|
|
66
|
-
|
|
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
|
-
|
|
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
|
-
|
|
75
|
-
|
|
76
|
-
|
|
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
|
-
|
|
53
|
+
<br>
|
|
98
54
|
|
|
99
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
116
|
-
<
|
|
117
|
-
|
|
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
|
-
|
|
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
|
-
|
|
73
|
+
## Content that stays organised
|
|
133
74
|
|
|
134
|
-
**
|
|
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
|
-
|
|
137
|
-
|
|
138
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
92
|
+
## Built on Elevate
|
|
159
93
|
|
|
160
|
-
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
**
|
|
115
|
+
**Only the CSS you use is generated.** Elevate reads your templates and writes a stylesheet with just those classes.
|
|
202
116
|
|
|
203
|
-
**
|
|
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
|
-
|
|
119
|
+
<br>
|
|
206
120
|
|
|
207
|
-
|
|
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
|
-
|
|
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
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
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
|
-
|
|
135
|
+
<br>
|
|
245
136
|
|
|
246
|
-
##
|
|
137
|
+
## Put it online
|
|
247
138
|
|
|
248
|
-
|
|
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
|
-
|
|
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
|
-
|
|
143
|
+
<br>
|
|
258
144
|
|
|
259
|
-
|
|
260
|
-
"channels": {
|
|
261
|
-
"journal": { "label": "Journal", "template": "post", "item": "post" }
|
|
262
|
-
}
|
|
263
|
-
```
|
|
145
|
+
## Guides
|
|
264
146
|
|
|
265
|
-
The
|
|
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
|
-
|
|
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
|
-
|
|
157
|
+
### For AI assistants
|
|
270
158
|
|
|
271
|
-
|
|
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
|
-
|
|
161
|
+
<br>
|
|
274
162
|
|
|
275
|
-
|
|
163
|
+
## Status
|
|
276
164
|
|
|
277
|
-
|
|
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
|
-
|
|
280
|
-
git clone https://github.com/DesignInTheBlack/verso.git
|
|
281
|
-
cd verso
|
|
282
|
-
npm install
|
|
283
|
-
npm test
|
|
284
|
-
```
|
|
167
|
+
## License
|
|
285
168
|
|
|
286
|
-
|
|
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)
|
package/editor/ext-tokens.js
CHANGED
|
@@ -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("
|
|
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
|
|
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
|
|
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.
|
|
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://
|
|
67
|
+
"homepage": "https://verso-docs.creative-cd9.workers.dev",
|
|
68
68
|
"bugs": {
|
|
69
69
|
"url": "https://github.com/DesignInTheBlack/verso/issues"
|
|
70
70
|
}
|
package/src/extensions/tokens.js
CHANGED
|
@@ -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.
|
|
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
|
};
|