1use super::facts::FactId;
9use super::ids::AnchorId;
10use super::xref::{SourceLoc, Target};
11use serde::{Deserialize, Serialize};
12
13#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
14#[serde(tag = "type", rename_all = "kebab-case")]
15pub enum Block {
16 Heading {
17 level: u8,
18 text: String,
19 anchor: AnchorId,
20 },
21 Paragraph {
22 content: Vec<Inline>,
23 },
24 Markdown {
27 markdown: MarkdownText,
28 },
29 Code {
30 lang: String,
31 code: String,
32 #[serde(skip_serializing_if = "Option::is_none")]
33 title: Option<String>,
34 },
35 List {
36 ordered: bool,
37 items: Vec<Vec<Inline>>,
38 },
39 Table {
40 columns: Vec<String>,
41 rows: Vec<Vec<Vec<Inline>>>,
42 },
43 Callout {
44 kind: CalloutKind,
45 #[serde(skip_serializing_if = "Option::is_none")]
46 title: Option<String>,
47 body: Vec<Block>,
48 },
49 Diagram {
52 kind: DiagramKind,
53 source: String,
54 links: Vec<(String, Target)>,
55 #[serde(skip_serializing_if = "Option::is_none")]
56 caption: Option<String>,
57 },
58 Cards {
59 cards: Vec<Card>,
60 },
61 Stats {
63 stats: Vec<Stat>,
64 },
65 Symbol {
67 symbol: Box<SymbolBlock>,
68 },
69 Narrative {
72 slot: String,
73 #[serde(skip_serializing_if = "Option::is_none")]
74 text: Option<MarkdownText>,
75 fallback: Vec<Block>,
76 },
77}
78
79#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
80#[serde(tag = "type", rename_all = "kebab-case")]
81pub enum Inline {
82 Text {
83 text: String,
84 },
85 Code {
86 code: String,
87 },
88 Strong {
89 content: Vec<Inline>,
90 },
91 Emph {
92 content: Vec<Inline>,
93 },
94 Link {
95 to: Target,
96 content: Vec<Inline>,
97 },
98 Fact {
100 fact: FactId,
101 },
102}
103
104impl Inline {
105 pub fn text(s: impl Into<String>) -> Self {
106 Inline::Text { text: s.into() }
107 }
108
109 pub fn code(s: impl Into<String>) -> Self {
110 Inline::Code { code: s.into() }
111 }
112
113 pub fn strong(s: impl Into<String>) -> Self {
114 Inline::Strong {
115 content: vec![Inline::text(s)],
116 }
117 }
118
119 pub fn link(to: Target, label: impl Into<String>) -> Self {
120 Inline::Link {
121 to,
122 content: vec![Inline::text(label)],
123 }
124 }
125
126 pub fn code_link(to: Target, code: impl Into<String>) -> Self {
127 Inline::Link {
128 to,
129 content: vec![Inline::code(code)],
130 }
131 }
132
133 pub fn fact(id: FactId) -> Self {
134 Inline::Fact { fact: id }
135 }
136}
137
138impl Block {
139 pub fn heading(level: u8, text: impl Into<String>) -> Self {
140 let text = text.into();
141 Block::Heading {
142 level,
143 anchor: super::ids::anchor_for(&text),
144 text,
145 }
146 }
147
148 pub fn para(content: Vec<Inline>) -> Self {
149 Block::Paragraph { content }
150 }
151
152 pub fn text(s: impl Into<String>) -> Self {
153 Block::Paragraph {
154 content: vec![Inline::text(s)],
155 }
156 }
157
158 pub fn note(body: impl Into<String>) -> Self {
159 Block::Callout {
160 kind: CalloutKind::Note,
161 title: None,
162 body: vec![Block::text(body)],
163 }
164 }
165}
166
167#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
169pub struct MarkdownText {
170 pub source: String,
171 pub origin: MarkdownOrigin,
172 #[serde(skip_serializing_if = "Option::is_none")]
173 pub from: Option<SourceLoc>,
174}
175
176#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
177#[serde(rename_all = "kebab-case")]
178pub enum MarkdownOrigin {
179 Doc,
181 Comment,
183 Commit,
185 Llm,
187}
188
189#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
190#[serde(rename_all = "kebab-case")]
191pub enum CalloutKind {
192 Note,
193 Tip,
194 Caution,
195 Danger,
196}
197
198#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
199#[serde(rename_all = "kebab-case")]
200pub enum DiagramKind {
201 Mermaid,
202}
203
204#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
205pub struct Card {
206 pub title: String,
207 pub to: Target,
208 #[serde(skip_serializing_if = "Option::is_none")]
209 pub description: Option<String>,
210}
211
212#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
213pub struct Stat {
214 pub label: String,
215 pub fact: FactId,
216}
217
218#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
220pub struct SymbolBlock {
221 pub id: super::ids::SymbolId,
222 pub anchor: AnchorId,
223 pub kind: String,
225 pub name: String,
226 pub lang: String,
228 pub signature: String,
229 #[serde(skip_serializing_if = "Option::is_none")]
230 pub doc: Option<MarkdownText>,
231 #[serde(default, skip_serializing_if = "Vec::is_empty")]
232 pub params: Vec<ParamRow>,
233 #[serde(skip_serializing_if = "Option::is_none")]
234 pub returns: Option<String>,
235 #[serde(skip_serializing_if = "Option::is_none")]
237 pub deprecated: Option<String>,
238 #[serde(default, skip_serializing_if = "Vec::is_empty")]
240 pub badges: Vec<String>,
241 pub source: SourceLoc,
242}
243
244#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
245pub struct ParamRow {
246 pub name: String,
247 pub ty: String,
248}