cli + tui to publish to leaflet (wip) & manage tasks, notes & watch/read lists 馃崈
desertthunder.dev
charm
leaflet
readability
golang
1---
2title: Publishing Workflow
3sidebar_label: Workflow
4description: Post, patch, drafts, pulling, and syncing documents.
5sidebar_position: 4
6---
7
8# Publishing Workflow
9
10## Converting Notes to Leaflet Documents
11
12Noteleaf converts markdown notes to leaflet's rich text block format:
13
14**Supported Markdown Features**:
15
16- Headers (`#`, `##`, `###`, etc.)
17- Paragraphs
18- Bold (`**bold**`)
19- Italic (`*italic*`)
20- Code (`inline code`)
21- Strikethrough (`~~text~~`)
22- Links (`[text](url)`)
23- Code blocks (` ```language ... ``` `)
24- Blockquotes (`> quote`)
25- Lists (ordered and unordered)
26- Horizontal rules (`---`)
27
28**Conversion Process**:
29
301. Parse markdown into AST (abstract syntax tree)
312. Convert AST nodes to leaflet block records
323. Process text formatting into facets
334. Validate document structure
345. Upload to leaflet.pub via AT Protocol
35
36## Creating a New Document
37
38Publish a local note as a new leaflet document:
39
40```sh
41noteleaf pub post 123
42```
43
44This:
45
461. Converts the note to leaflet format
472. Creates a new document on leaflet.pub
483. Links the note to the document (stores the rkey)
494. Marks the note as published
50
51**Create as draft**:
52
53```sh
54noteleaf pub post 123 --draft
55```
56
57Drafts are saved to leaflet but not publicly visible until you publish them.
58
59**Preview before posting**:
60
61```sh
62noteleaf pub post 123 --preview
63```
64
65Shows what the document will look like without actually posting.
66
67**Validate conversion**:
68
69```sh
70noteleaf pub post 123 --validate
71```
72
73Checks if the markdown converts correctly to leaflet format without posting.
74
75**Save to file**:
76
77```sh
78noteleaf pub post 123 --preview --output document.json
79noteleaf pub post 123 --preview --output document.txt --plaintext
80```
81
82## Updating Published Documents
83
84Update an existing leaflet document from a local note:
85
86```sh
87noteleaf pub patch 123
88```
89
90Requirements:
91
92- Note must have been previously posted or pulled from leaflet
93- Note must have a leaflet record key (rkey) in the database
94
95**Preserve draft/published status**: The `patch` command maintains the document's current status. If it's published, it stays published. If it's a draft, it stays a draft.
96
97**Preview changes**:
98
99```sh
100noteleaf pub patch 123 --preview
101```
102
103**Validate before patching**:
104
105```sh
106noteleaf pub patch 123 --validate
107```
108
109## Managing Drafts
110
111**Create as draft**:
112
113```sh
114noteleaf pub post 123 --draft
115```
116
117**Update draft**:
118
119```sh
120noteleaf pub patch 123
121```
122
123**List drafts**:
124
125```sh
126noteleaf pub list --draft
127```
128
129**Publish a draft**: Edit the draft on leaflet.pub or use the API to change status (command support coming in future versions).
130
131## Pulling Documents from Leaflet
132
133Sync leaflet documents to local notes:
134
135```sh
136noteleaf pub pull
137```
138
139This:
140
1411. Authenticates with leaflet.pub
1422. Fetches all documents in your repository
1433. Creates new notes for documents not yet synced
1444. Updates existing notes that have changed
145
146**Matching logic**: Notes are matched to leaflet documents by their record key (rkey) stored in the database.
147If a document doesn't have a corresponding note, a new one is created. If it does, the note is updated only if the content has changed (using CID for change detection).