verso-cms 0.0.0-stage → 0.1.2
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/LICENSE +21 -0
- package/README.md +288 -2
- package/bin/verso.js +16 -0
- package/editor/door.js +139 -0
- package/editor/editor.js +1880 -0
- package/editor/elevate.css +2158 -0
- package/editor/ext-attrs.js +87 -0
- package/editor/ext-blocks.js +422 -0
- package/editor/ext-builder.js +819 -0
- package/editor/ext-channels.js +574 -0
- package/editor/ext-components.js +160 -0
- package/editor/ext-history.js +242 -0
- package/editor/ext-palette.js +307 -0
- package/editor/ext-people.js +345 -0
- package/editor/ext-repeaters.js +143 -0
- package/editor/ext-screens.js +94 -0
- package/editor/ext-site-settings.js +318 -0
- package/editor/ext-site-view.js +632 -0
- package/editor/ext-tokens.js +1166 -0
- package/editor/new-page.js +252 -0
- package/editor/rich.js +23 -0
- package/package.json +69 -4
- package/src/blocks.js +269 -0
- package/src/box.js +339 -0
- package/src/build.js +210 -0
- package/src/cli.js +161 -0
- package/src/color.js +137 -0
- package/src/components.js +223 -0
- package/src/elevate.js +74 -0
- package/src/errors.js +46 -0
- package/src/extensions/README.md +70 -0
- package/src/extensions/blocks.js +294 -0
- package/src/extensions/builder.js +734 -0
- package/src/extensions/channels.js +341 -0
- package/src/extensions/components.js +141 -0
- package/src/extensions/history.js +169 -0
- package/src/extensions/palette.js +31 -0
- package/src/extensions/people.js +113 -0
- package/src/extensions/site-settings.js +251 -0
- package/src/extensions/site-view.js +381 -0
- package/src/extensions/tags.js +15 -0
- package/src/extensions/tokens.js +587 -0
- package/src/fonts.js +139 -0
- package/src/git.js +419 -0
- package/src/html-edit.js +942 -0
- package/src/images.js +116 -0
- package/src/people.js +286 -0
- package/src/rich.js +124 -0
- package/src/scaffold.js +185 -0
- package/src/screens.js +65 -0
- package/src/server.js +693 -0
- package/src/site.js +618 -0
- package/src/template.js +915 -0
- package/src/video.js +29 -0
- package/starter/Dockerfile +20 -0
- package/starter/README.md +49 -0
- package/starter/blocks/call-to-action.html +6 -0
- package/starter/blocks/features.html +15 -0
- package/starter/blocks/hero.html +8 -0
- package/starter/blocks/image-and-text.html +8 -0
- package/starter/blocks/latest-posts.html +20 -0
- package/starter/blocks/post-index.html +30 -0
- package/starter/blocks/quote.html +9 -0
- package/starter/blocks/site-footer.html +8 -0
- package/starter/blocks/site-nav.html +8 -0
- package/starter/blocks/tag-list.html +10 -0
- package/starter/blocks/tagged-posts.html +19 -0
- package/starter/blocks/team.html +15 -0
- package/starter/blocks/text.html +4 -0
- package/starter/content/404/page.json +21 -0
- package/starter/content/about/page.json +65 -0
- package/starter/content/journal/designing-for-the-morning-shift/body.html +22 -0
- package/starter/content/journal/designing-for-the-morning-shift/checklist.jpg +0 -0
- package/starter/content/journal/designing-for-the-morning-shift/cover.jpg +0 -0
- package/starter/content/journal/designing-for-the-morning-shift/page.json +17 -0
- package/starter/content/journal/page.json +19 -0
- package/starter/content/journal/the-first-week/body.html +17 -0
- package/starter/content/journal/the-first-week/cover.jpg +0 -0
- package/starter/content/journal/the-first-week/page.json +17 -0
- package/starter/content/journal/the-first-week/wall-of-cards.jpg +0 -0
- package/starter/content/page.json +94 -0
- package/starter/content/site.json +88 -0
- package/starter/content/studio-table.jpg +0 -0
- package/starter/content/topics/page.json +27 -0
- package/starter/dockerignore +5 -0
- package/starter/elevate/config/design.ts +30 -0
- package/starter/elevate/config/elevate.ts +16 -0
- package/starter/elevate/config/syntax.ts +6 -0
- package/starter/elevate/design/site.ts +9 -0
- package/starter/elevate/design/tokens.json +20 -0
- package/starter/elevate/extend/fonts.css +1 -0
- package/starter/gitignore +6 -0
- package/starter/netlify.toml +5 -0
- package/starter/parts/.gitkeep +0 -0
- package/starter/public/favicon.svg +1 -0
- package/starter/templates/page.html +20 -0
- package/starter/templates/page.layout.json +23 -0
- package/starter/templates/post.html +65 -0
- package/starter/verso.defaults.json +33 -0
- package/starter-blank/blocks/site-footer.html +3 -0
- package/starter-blank/blocks/site-nav.html +8 -0
- package/starter-blank/blocks/text.html +4 -0
- package/starter-blank/content/404/page.json +18 -0
- package/starter-blank/content/page.json +18 -0
- package/starter-blank/content/site.json +36 -0
- package/starter-blank/elevate/design/tokens.json +10 -0
- package/starter-blank/templates/page.html +17 -0
- package/starter-blank/verso.defaults.json +26 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Kenneth Pickett
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,289 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<picture>
|
|
3
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/DesignInTheBlack/verso/main/docs/mark-dark.svg">
|
|
4
|
+
<img src="https://raw.githubusercontent.com/DesignInTheBlack/verso/main/docs/mark-light.svg" width="88" height="64" alt="">
|
|
5
|
+
</picture>
|
|
6
|
+
</p>
|
|
2
7
|
|
|
3
|
-
|
|
8
|
+
<h1 align="center">Verso</h1>
|
|
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>
|
|
13
|
+
|
|
14
|
+

|
|
15
|
+
|
|
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
|
+

|
|
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
|
|
36
|
+
|
|
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.
|
|
38
|
+
|
|
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>
|
|
45
|
+
|
|
46
|
+
## Start a site
|
|
47
|
+
|
|
48
|
+
You need [Node.js](https://nodejs.org) 20.19 or newer and [git](https://git-scm.com).
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
npx verso-cms new my-site
|
|
52
|
+
cd my-site
|
|
53
|
+
npm run dev
|
|
54
|
+
```
|
|
55
|
+
|
|
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.
|
|
57
|
+
|
|
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.
|
|
59
|
+
|
|
60
|
+
<details>
|
|
61
|
+
<summary>On Windows</summary>
|
|
62
|
+
|
|
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>
|
|
65
|
+
|
|
66
|
+
## A site in a box
|
|
67
|
+
|
|
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
|
+
```
|
|
73
|
+
|
|
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
|
|
96
|
+
|
|
97
|
+
Everything a site needs can be made in the browser, without opening a file:
|
|
98
|
+
|
|
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.
|
|
106
|
+
|
|
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.
|
|
108
|
+
|
|
109
|
+
## Building a site by hand
|
|
110
|
+
|
|
111
|
+
Templates are plain HTML. Styles are Elevate classes. Besides HTML, a template holds fields, lists, repeaters, conditions, references and parts.
|
|
112
|
+
|
|
113
|
+
**Fields** are written where their value goes, as `name:type:modifiers`:
|
|
114
|
+
|
|
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
|
+
```
|
|
123
|
+
|
|
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 |
|
|
131
|
+
|
|
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.
|
|
133
|
+
|
|
134
|
+
**Lists** repeat their contents for each page in a folder, with `{{ else }}` for when there are none:
|
|
135
|
+
|
|
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
|
+
```
|
|
144
|
+
|
|
145
|
+
After the folder, add any of these, in any order:
|
|
146
|
+
|
|
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 |
|
|
157
|
+
|
|
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.
|
|
159
|
+
|
|
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`.
|
|
161
|
+
|
|
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:
|
|
163
|
+
|
|
164
|
+
```html
|
|
165
|
+
{{ if:paging.next }}<a href="{{ paging.next }}">Older posts</a>{{ /if }}
|
|
166
|
+
```
|
|
167
|
+
|
|
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.
|
|
171
|
+
|
|
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
|
+
```
|
|
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>
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
The list needs an element to itself. In the editor, items are added, moved, duplicated and removed in place.
|
|
200
|
+
|
|
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`.
|
|
202
|
+
|
|
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.
|
|
204
|
+
|
|
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:
|
|
206
|
+
|
|
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.
|
|
218
|
+
|
|
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.
|
|
220
|
+
|
|
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
|
+
}
|
|
242
|
+
```
|
|
243
|
+
|
|
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.
|
|
245
|
+
|
|
246
|
+
## In the editor
|
|
247
|
+
|
|
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.
|
|
254
|
+
|
|
255
|
+
### Channels
|
|
256
|
+
|
|
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.
|
|
258
|
+
|
|
259
|
+
```json
|
|
260
|
+
"channels": {
|
|
261
|
+
"journal": { "label": "Journal", "template": "post", "item": "post" }
|
|
262
|
+
}
|
|
263
|
+
```
|
|
264
|
+
|
|
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").
|
|
266
|
+
|
|
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.
|
|
268
|
+
|
|
269
|
+
If a channel's folder or template doesn't exist, the panel says which and how to fix it.
|
|
270
|
+
|
|
271
|
+
## Status
|
|
272
|
+
|
|
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.
|
|
274
|
+
|
|
275
|
+
Still to do before calling it finished: try it on macOS and Windows, in Safari and Firefox, and on more real sites.
|
|
276
|
+
|
|
277
|
+
## Developing Verso
|
|
278
|
+
|
|
279
|
+
```bash
|
|
280
|
+
git clone https://github.com/DesignInTheBlack/verso.git
|
|
281
|
+
cd verso
|
|
282
|
+
npm install
|
|
283
|
+
npm test
|
|
284
|
+
```
|
|
285
|
+
|
|
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`.
|
package/bin/verso.js
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Checks Node's version before loading anything else, so an old Node gets a
|
|
3
|
+
// plain message instead of a crash from deep inside a dependency.
|
|
4
|
+
// The rest of the command line lives in src/cli.js.
|
|
5
|
+
|
|
6
|
+
const [major, minor] = process.versions.node.split('.').map(Number);
|
|
7
|
+
const supported = major >= 23 || (major === 22 && minor >= 12) || (major === 20 && minor >= 19);
|
|
8
|
+
|
|
9
|
+
if (!supported) {
|
|
10
|
+
const red = (s) => (process.stderr.isTTY ? `\x1b[31m${s}\x1b[0m` : s);
|
|
11
|
+
console.error(red(`× Verso needs Node.js 20.19 or newer, and this computer has ${process.versions.node}.`));
|
|
12
|
+
console.error(' Install the LTS version from https://nodejs.org, open a new terminal, and run this again.');
|
|
13
|
+
process.exit(1);
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
await import('../src/cli.js');
|
package/editor/door.js
ADDED
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
// The pages in front of the editor on a boxed site (verso serve): signing
|
|
2
|
+
// in, setting up the first owner, and using an invite or new-password link.
|
|
3
|
+
//
|
|
4
|
+
// These are whole pages made on the server, plain forms that work without
|
|
5
|
+
// JavaScript. They live here, with the rest of the interface, so their
|
|
6
|
+
// classes are compiled into the editor's stylesheet with everything else.
|
|
7
|
+
|
|
8
|
+
const ui = (classes) => classes;
|
|
9
|
+
const esc = (s) => String(s ?? '').replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"');
|
|
10
|
+
|
|
11
|
+
const MARK = `<span class="${ui("row:x-center:y-center w:d12 h:d12 bd:round-full bg-color:proof text:paper child:no-shrink")}" aria-hidden="true"><svg width="26" height="26" viewBox="1 3 18 18"><path d="M5 6.5 10 17l5-10.5" fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"/></svg></span>`;
|
|
12
|
+
|
|
13
|
+
const LABEL = ui("font:small:medium text:ink");
|
|
14
|
+
const INPUT = ui("w:full h:d12 pd-x:d4 bd:round-d3 bd:width-px:solid:line bg-color:paper font:base text:ink @focus:[bd:proof_shadow:proof-focus_outline:none] transition:fast");
|
|
15
|
+
const BUTTON = ui("w:full h:d12 mg-t:d2 bd:width-0 bd:round-pill bg-color:proof text:paper font:base:semibold cursor:pointer @hover:[bg-color:proof-2] @focus-visible:[outline:d0:solid:ink] transition:fast");
|
|
16
|
+
const QUIET = ui("font:small text:ink-3:relaxed");
|
|
17
|
+
const LINK = ui("text:ink:underline @hover:[text:proof-2]");
|
|
18
|
+
|
|
19
|
+
const field = ({ name, label, type = 'text', value = '', autocomplete, hint = '', focus = false }) => `
|
|
20
|
+
<label class="${ui("col gap:d1")}">
|
|
21
|
+
<span class="${LABEL}">${label}</span>
|
|
22
|
+
<input class="${INPUT}" type="${type}" name="${name}" value="${esc(value)}" autocomplete="${autocomplete}" required${type === 'password' ? ' minlength="8" data-secret' : ''}${focus ? ' autofocus' : ''}>
|
|
23
|
+
${hint ? `<span class="${ui("font:tiny text:ink-3")}">${hint}</span>` : ''}
|
|
24
|
+
</label>`;
|
|
25
|
+
|
|
26
|
+
// One box under the password: tick it to read what you typed.
|
|
27
|
+
const REVEAL = `
|
|
28
|
+
<label class="${ui("row:y-center gap:d2 font:small text:ink-3 cursor:pointer select:none")}" data-reveal hidden>
|
|
29
|
+
<input type="checkbox" class="${ui("w:d4 h:d4 cursor:pointer")}"> Show the password
|
|
30
|
+
</label>
|
|
31
|
+
<script>(() => { const box = document.querySelector('[data-reveal]'); box.hidden = false; box.querySelector('input').addEventListener('change', (e) => document.querySelectorAll('[data-secret]').forEach((i) => { i.type = e.target.checked ? 'text' : 'password'; })); })();</script>`;
|
|
32
|
+
|
|
33
|
+
const problem = (message) => (message
|
|
34
|
+
? `<p role="alert" class="${ui("pd:d4:d3 bd:round-d3 bg-color:proof-soft font:small:medium text:proof-2")}">${esc(message)}</p>`
|
|
35
|
+
: '');
|
|
36
|
+
|
|
37
|
+
const page = ({ site, title, heading, intro = '', body }) => `<!DOCTYPE html>
|
|
38
|
+
<html lang="en">
|
|
39
|
+
<head>
|
|
40
|
+
<meta charset="utf-8">
|
|
41
|
+
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
42
|
+
<meta name="robots" content="noindex">
|
|
43
|
+
<title>${esc(title)} · ${esc(site)}</title>
|
|
44
|
+
<link rel="stylesheet" href="/__verso/elevate.css">
|
|
45
|
+
</head>
|
|
46
|
+
<body class="${ui("min-h:hScreen col:x-center pd:d5 bg-color:paper-2 font:ui:base text:ink /md/ pd-y:c2")}">
|
|
47
|
+
<main class="${ui("col gap:d8 w:full max-w:s1 mg-y:auto")}">
|
|
48
|
+
<header class="${ui("col gap:d5")}">
|
|
49
|
+
${MARK}
|
|
50
|
+
<div class="${ui("col gap:d2")}">
|
|
51
|
+
<p class="${ui("font:small:medium text:ink-3")}">${esc(site)}</p>
|
|
52
|
+
<h1 class="${ui("font:h4:semibold text:ink:snug")}">${heading}</h1>
|
|
53
|
+
${intro ? `<p class="${ui("font:base text:ink-3:relaxed")}">${intro}</p>` : ''}
|
|
54
|
+
</div>
|
|
55
|
+
</header>
|
|
56
|
+
${body}
|
|
57
|
+
<p class="${QUIET}"><a class="${LINK}" href="/">Back to the site</a></p>
|
|
58
|
+
</main>
|
|
59
|
+
</body>
|
|
60
|
+
</html>`;
|
|
61
|
+
|
|
62
|
+
const form = (action, inner) => `<form method="post" action="${action}" class="${ui("col gap:d4")}">${inner}</form>`;
|
|
63
|
+
|
|
64
|
+
export function signInPage({ site, error = '', email = '', to = '' }) {
|
|
65
|
+
return page({
|
|
66
|
+
site,
|
|
67
|
+
title: 'Sign in',
|
|
68
|
+
heading: 'Sign in to edit',
|
|
69
|
+
body: `${form('/edit', `
|
|
70
|
+
${problem(error)}
|
|
71
|
+
<input type="hidden" name="to" value="${esc(to)}">
|
|
72
|
+
${field({ name: 'email', label: 'Email', type: 'email', value: email, autocomplete: 'username', focus: !email })}
|
|
73
|
+
${field({ name: 'password', label: 'Password', type: 'password', autocomplete: 'current-password', focus: !!email })}
|
|
74
|
+
${REVEAL}
|
|
75
|
+
<button class="${BUTTON}">Sign in</button>`)}
|
|
76
|
+
<p class="${QUIET}">Forgotten your password? Ask an owner of this site for a new link.</p>`,
|
|
77
|
+
});
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
// Nobody can edit yet, and the only way to become the first owner is the
|
|
81
|
+
// link the server wrote to its log.
|
|
82
|
+
export function notSetUpPage({ site }) {
|
|
83
|
+
return page({
|
|
84
|
+
site,
|
|
85
|
+
title: 'Set up editing',
|
|
86
|
+
heading: 'Editing isn\'t set up yet',
|
|
87
|
+
intro: 'When this site started, it wrote a setup link in its log. Open that link to become the site\'s first owner.',
|
|
88
|
+
body: `<p class="${ui("pd:d4 bd:round-d3 bg-color:paper bd:width-px:solid:line font:small text:ink-3:relaxed")}">Can't find it? Restart the site, or run <code class="${ui("pd:d1:d0 bd:round-d1 bg-color:paper-2 font:mono:small text:ink")}">npx verso owner</code> in its folder, and a fresh link is written.</p>`,
|
|
89
|
+
});
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
export function deadLinkPage({ site }) {
|
|
93
|
+
return page({
|
|
94
|
+
site,
|
|
95
|
+
title: 'Link not found',
|
|
96
|
+
heading: 'This link doesn\'t work any more',
|
|
97
|
+
intro: 'It has been used already, or it\'s more than seven days old. Ask an owner of the site for a new one.',
|
|
98
|
+
body: `<a href="/edit" class="${ui("row:x-center:y-center w:full h:d12 bd:round-pill bd:width-px:solid:line bg-color:paper font:base:semibold text:ink @hover:[bd:ink-3] @focus-visible:[outline:d0:solid:proof] transition:fast")}">Go to sign in</a>`,
|
|
99
|
+
});
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
// One page for the three kinds of link: the first owner's, an invite, and a
|
|
103
|
+
// new password.
|
|
104
|
+
export function joinPage({ site, link, token, error = '', values = {} }) {
|
|
105
|
+
const hidden = `<input type="hidden" name="t" value="${esc(token)}">`;
|
|
106
|
+
if (link.kind === 'reset') {
|
|
107
|
+
return page({
|
|
108
|
+
site,
|
|
109
|
+
title: 'New password',
|
|
110
|
+
heading: 'Choose a new password',
|
|
111
|
+
intro: `For ${esc(link.email)}. Your other browsers will be signed out.`,
|
|
112
|
+
body: form('/edit/join', `
|
|
113
|
+
${problem(error)}${hidden}
|
|
114
|
+
<input type="hidden" name="email" value="${esc(link.email)}" autocomplete="username">
|
|
115
|
+
${field({ name: 'password', label: 'New password', type: 'password', autocomplete: 'new-password', hint: 'At least 8 characters. A few words together works well.', focus: true })}
|
|
116
|
+
${REVEAL}
|
|
117
|
+
<button class="${BUTTON}">Save and sign in</button>`),
|
|
118
|
+
});
|
|
119
|
+
}
|
|
120
|
+
const first = link.kind === 'setup';
|
|
121
|
+
const role = link.role === 'owner' ? 'an owner' : 'an editor';
|
|
122
|
+
return page({
|
|
123
|
+
site,
|
|
124
|
+
title: first ? 'Set up editing' : 'Join',
|
|
125
|
+
heading: first ? 'Set up editing' : `Start editing ${esc(site)}`,
|
|
126
|
+
intro: first
|
|
127
|
+
? 'You\'ll be an owner of this site. Owners can change everything and invite other people.'
|
|
128
|
+
: `${link.by ? `${esc(link.by)} invited you` : 'You\'ve been invited'} as ${role}. Choose a password and you're in.`,
|
|
129
|
+
body: form('/edit/join', `
|
|
130
|
+
${problem(error)}${hidden}
|
|
131
|
+
${field({ name: 'name', label: 'Your name', value: values.name ?? link.name, autocomplete: 'name', focus: !(values.name ?? link.name) })}
|
|
132
|
+
${first
|
|
133
|
+
? field({ name: 'email', label: 'Email', type: 'email', value: values.email || '', autocomplete: 'username', hint: 'What you\'ll sign in with. Verso never sends email.' })
|
|
134
|
+
: `<div class="${ui("col gap:d1")}"><span class="${LABEL}">Email</span><span class="${ui("row:y-center h:d12 pd-x:d4 bd:round-d3 bg-color:line font:base text:ink-3")}">${esc(link.email)}</span><input type="hidden" name="email" value="${esc(link.email)}" autocomplete="username"></div>`}
|
|
135
|
+
${field({ name: 'password', label: 'Password', type: 'password', autocomplete: 'new-password', hint: 'At least 8 characters. A few words together works well.', focus: !!(values.name ?? link.name) && !first })}
|
|
136
|
+
${REVEAL}
|
|
137
|
+
<button class="${BUTTON}">${first ? 'Set up and start editing' : 'Start editing'}</button>`),
|
|
138
|
+
});
|
|
139
|
+
}
|