wcl_wdoc 0.11.0-alpha

WCL documentation format — build structured docs with WCL, render to HTML
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122

use indexmap::IndexMap;

/// A complete wdoc document with sections, pages, and styles.
#[derive(Debug, Clone)]
pub struct WdocDocument {
    pub name: String,
    pub title: String,
    pub version: Option<String>,
    pub author: Option<String>,
    pub sections: Vec<Section>,
    pub pages: Vec<Page>,
    pub styles: Vec<WdocStyle>,
    pub extra_css: String,
}

/// A section in the document outline. Ordering matches declaration order.
#[derive(Debug, Clone)]
pub struct Section {
    /// Fully-qualified dotted path (e.g. "my-docs.getting-started.installation")
    pub id: String,
    /// Short ID (the block's inline ID, e.g. "installation")
    pub short_id: String,
    /// Display title (from inline arg)
    pub title: String,
    pub children: Vec<Section>,
}

/// A page of content, belonging to a section.
#[derive(Debug, Clone)]
pub struct Page {
    pub id: String,
    pub section_id: String,
    pub title: String,
    pub layout: Layout,
    pub signals: Vec<WdocSignal>,
    pub bindings: Vec<WdocBinding>,
}

/// The layout container for a page.
#[derive(Debug, Clone)]
pub struct Layout {
    pub children: Vec<LayoutItem>,
}

/// An item inside a layout or split — either a split group or a content block.
#[derive(Debug, Clone)]
pub enum LayoutItem {
    SplitGroup(SplitGroup),
    Content(ContentBlock),
}

/// Direction of a split group.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SplitDirection {
    /// Columns side-by-side (flex-direction: row)
    Vertical,
    /// Rows stacked (flex-direction: column)
    Horizontal,
}

/// A group of splits in a given direction (vsplit or hsplit).
#[derive(Debug, Clone)]
pub struct SplitGroup {
    pub direction: SplitDirection,
    pub splits: Vec<Split>,
}

/// A single split pane with a size percentage and nested content.
#[derive(Debug, Clone)]
pub struct Split {
    pub size_percent: f64,
    pub children: Vec<LayoutItem>,
}

/// A content block inside a split, rendered by a template function.
#[derive(Debug, Clone)]
pub struct ContentBlock {
    /// Block kind (e.g. "heading", "paragraph", "image", "code")
    pub kind: String,
    /// Optional block ID for anchor linking
    pub id: Option<String>,
    /// HTML output from the template function
    pub rendered_html: String,
    /// Style class from @style decorator
    pub style: Option<String>,
}

/// A page-scoped dynamic value available to wdoc runtime bindings.
#[derive(Debug, Clone)]
pub struct WdocSignal {
    pub name: String,
    pub initial: serde_json::Value,
    pub type_name: Option<String>,
}

/// A declarative runtime binding from a signal value to an HTML/SVG property.
#[derive(Debug, Clone)]
pub struct WdocBinding {
    pub name: Option<String>,
    pub signal: String,
    pub target: String,
    pub property: String,
    pub path: Option<String>,
    pub format: Option<String>,
}

/// A named style definition.
#[derive(Debug, Clone)]
pub struct WdocStyle {
    /// Style name ("default" is auto-applied to all content blocks)
    pub name: String,
    pub rules: Vec<StyleRule>,
}

/// A CSS rule targeting a specific content block kind.
#[derive(Debug, Clone)]
pub struct StyleRule {
    /// Target content block kind (e.g. "heading", "paragraph")
    pub target: String,
    /// CSS properties (name → value)
    pub properties: IndexMap<String, String>,
}