seth.computer
this repo has no description
Content-types and lexicons
Made some decisions about how to handle all this. Wanted to keep things
simple but ended up going with sitebase-specific lexicons to make sure
we're using the `site.standard.document.content` union type properly.
This means setting up a sitebase PDS sooner than later so these can be
defined and published there. Going to do it right!
+170
+23
docs/content-types.md
+23
docs/content-types.md
···
1
+
# Content Types
2
+
3
+
Sitebase is designed to be flexible and work with any `standard.site` data. However, due to the potential complexity of working with app-specific content types like those of leaflet.pub or pckt.blog, currently support is limited for working with them.
4
+
5
+
As defined in [the lexicon documentation](./lexicons.md), sitebase defines two simple content lexicons: `pub.sitebase.content.html` and `pub.sitebase.content.markdown`.
6
+
7
+
## Content Type Handling in CLI
8
+
9
+
The CLI only supports editing documents with sitebase content types:
10
+
11
+
| Content `$type` | `doc edit` | `doc view` | `doc export` |
12
+
|-----------------|------------|------------|--------------|
13
+
| `pub.sitebase.content.markdown` | Supported | Supported | Supported |
14
+
| `pub.sitebase.content.html` | Supported | Supported | Supported |
15
+
| Other (pckt.blog, etc.) | Blocked | Supported (raw display) | Supported (raw content) |
16
+
17
+
When `doc edit` encounters a non-sitebase content type:
18
+
19
+
```
20
+
Error: Cannot edit document with content type "blog.pckt.content.block"
21
+
Sitebase only supports editing documents with pub.sitebase.content.* types.
22
+
Use `doc view` to inspect the document.
23
+
```
+147
docs/lexicons.md
+147
docs/lexicons.md
···
1
+
# Sitebase Lexicons
2
+
3
+
Sitebase defines its own lexicons under the `pub.sitebase.*` namespace for content types and draft handling.
4
+
5
+
## Why Custom Lexicons?
6
+
7
+
The `site.standard.document` schema defines `content` as an open union, allowing different services to define their own content type schemas. Each service (leaflet, pckt.blog, sitebase) uses their own namespaced types.
8
+
9
+
Sitebase needs custom lexicons for:
10
+
11
+
1. **Content types** - markdown and HTML content with proper structure
12
+
2. **Drafts** - standard.site doesn't have a draft concept; we need our own
13
+
14
+
## Lexicon Definitions
15
+
16
+
### `pub.sitebase.content.markdown`
17
+
18
+
Markdown content for documents.
19
+
20
+
```json
21
+
{
22
+
"lexicon": 1,
23
+
"id": "pub.sitebase.content.markdown",
24
+
"defs": {
25
+
"main": {
26
+
"type": "object",
27
+
"required": ["markdown"],
28
+
"properties": {
29
+
"markdown": {
30
+
"type": "string",
31
+
"description": "The markdown content"
32
+
}
33
+
}
34
+
}
35
+
}
36
+
}
37
+
```
38
+
39
+
**Usage in document:**
40
+
41
+
```json
42
+
{
43
+
"$type": "site.standard.document",
44
+
"title": "My Post",
45
+
"content": {
46
+
"$type": "pub.sitebase.content.markdown",
47
+
"markdown": "# Hello\n\nThis is my post."
48
+
}
49
+
}
50
+
```
51
+
52
+
### `pub.sitebase.content.html`
53
+
54
+
HTML content for documents.
55
+
56
+
```json
57
+
{
58
+
"lexicon": 1,
59
+
"id": "pub.sitebase.content.html",
60
+
"defs": {
61
+
"main": {
62
+
"type": "object",
63
+
"required": ["html"],
64
+
"properties": {
65
+
"html": {
66
+
"type": "string",
67
+
"description": "The HTML content"
68
+
}
69
+
}
70
+
}
71
+
}
72
+
}
73
+
```
74
+
75
+
### `pub.sitebase.draft`
76
+
77
+
Draft document storage. Drafts are stored separately from published documents.
78
+
79
+
```json
80
+
{
81
+
"lexicon": 1,
82
+
"id": "pub.sitebase.draft",
83
+
"defs": {
84
+
"main": {
85
+
"type": "record",
86
+
"key": "tid",
87
+
"description": "A draft document that hasn't been published yet",
88
+
"record": {
89
+
"type": "object",
90
+
"required": ["title", "content", "createdAt"],
91
+
"properties": {
92
+
"site": {
93
+
"type": "string",
94
+
"format": "at-uri",
95
+
"description": "AT URI of the publication this draft belongs to"
96
+
},
97
+
"title": {
98
+
"type": "string",
99
+
"description": "Draft title"
100
+
},
101
+
"path": {
102
+
"type": "string",
103
+
"description": "Intended URL path when published"
104
+
},
105
+
"description": {
106
+
"type": "string",
107
+
"description": "Short description or excerpt"
108
+
},
109
+
"content": {
110
+
"type": "union",
111
+
"refs": [
112
+
"pub.sitebase.content.markdown",
113
+
"pub.sitebase.content.html"
114
+
],
115
+
"description": "Draft content"
116
+
},
117
+
"tags": {
118
+
"type": "array",
119
+
"items": { "type": "string" },
120
+
"description": "Tags for categorization"
121
+
},
122
+
"createdAt": {
123
+
"type": "string",
124
+
"format": "datetime",
125
+
"description": "When the draft was created"
126
+
},
127
+
"updatedAt": {
128
+
"type": "string",
129
+
"format": "datetime",
130
+
"description": "When the draft was last updated"
131
+
}
132
+
}
133
+
}
134
+
}
135
+
}
136
+
}
137
+
```
138
+
139
+
## Publishing Lexicons
140
+
141
+
Lexicons should be published to the PDS at:
142
+
143
+
- `at://<did>/com.atproto.lexicon.schema/pub.sitebase.content.markdown`
144
+
- `at://<did>/com.atproto.lexicon.schema/pub.sitebase.content.html`
145
+
- `at://<did>/com.atproto.lexicon.schema/pub.sitebase.draft`
146
+
147
+
The DID should be the sitebase project's identity (associated with pub.sitebase domain).