Skip to main content

mdbook_gitinfo/
config.rs

1//! Configuration module for the `mdbook-gitinfo` preprocessor.
2//!
3//! This module defines [`GitInfoConfig`], the structure that holds all
4//! user-defined configuration options from the `[preprocessor.gitinfo]`
5//! section in `book.toml`. It also provides [`load_config`] to deserialize
6//! these values into the struct for use by the preprocessor.
7//!
8//! # Example `book.toml`
9//!
10//! ```toml
11//! [preprocessor.gitinfo]
12//! template   = "Date: {{date}} • Commit: {{hash}}"
13//! font-size  = "0.8em"
14//! separator  = " | "
15//! date-format = "%Y-%m-%d"
16//! time-format = "%H:%M:%S"
17//! branch      = "main"
18//! ```
19
20use mdbook_preprocessor::PreprocessorContext;
21use mdbook_preprocessor::errors::Error;
22use serde::Deserialize;
23
24#[derive(Debug, Deserialize, Default)]
25pub struct MessageConfig {
26    /// Header message template
27    pub header: Option<String>,
28    /// Footer message template
29    pub footer: Option<String>,
30    /// Default for both (used if header/footer not set)
31    pub both: Option<String>,
32}
33
34#[derive(Debug, Deserialize)]
35#[serde(untagged)]
36pub enum MarginSetting {
37    /// "1em"
38    One(String),
39    /// ["top", "right", "bottom", "left"] — supports 1–4 entries like CSS shorthand
40    Quad(Vec<String>),
41    /// { top = "...", right = "...", bottom = "...", left = "..." }
42    Sides {
43        top: Option<String>,
44        right: Option<String>,
45        bottom: Option<String>,
46        left: Option<String>,
47    },
48}
49
50impl Default for MarginSetting {
51    fn default() -> Self {
52        MarginSetting::One("0".to_string())
53    }
54}
55
56#[derive(Debug, Deserialize, Default)]
57pub struct MarginConfig {
58    pub header: Option<MarginSetting>,
59    pub footer: Option<MarginSetting>,
60    pub both: Option<MarginSetting>,
61}
62
63#[derive(Debug, Deserialize)]
64#[serde(untagged)]
65pub enum AlignSetting {
66    /// Legacy: align = "center"
67    One(String),
68    /// New: align = { header = "...", footer = "...", both = "..." }
69    Split {
70        header: Option<String>,
71        footer: Option<String>,
72        both: Option<String>,
73    },
74}
75
76impl Default for AlignSetting {
77    fn default() -> Self {
78        AlignSetting::One("center".to_string())
79    }
80}
81
82#[derive(Debug, Deserialize, Clone, Copy)]
83#[serde(rename_all = "lowercase")]
84pub enum ContributorsSource {
85    Git,
86    File,
87    Inline,
88}
89
90impl Default for ContributorsSource {
91    fn default() -> Self {
92        ContributorsSource::Git
93    }
94}
95
96/// Represents the user-defined configuration options under `[preprocessor.gitinfo]`
97/// in `book.toml`.
98///
99/// Each field is optional; defaults are handled in the preprocessor logic.
100/// The configuration allows users to control how commit metadata is formatted
101/// and rendered in the generated book.
102#[derive(Debug, Deserialize, Default)]
103pub struct GitInfoConfig {
104    /// Gate to turn the preprocessor on/off without removing the section.
105    /// Default: true (when omitted).
106    pub enable: Option<bool>,
107
108    /// The formatting style of the git data (currently unused, reserved for future use).
109    pub format: Option<String>,
110
111    /// Template string defining how git metadata is rendered.
112    ///
113    /// Supported placeholders:
114    /// - `{{hash}}` → short commit hash
115    /// - `{{long}}` → full commit hash
116    /// - `{{tag}}` → lastest tag or user defined
117    /// - `{{date}}` → commit date
118    /// - `{{sep}}` → separator string
119    /// (Deprecated) Old single template. If present, used as a fallback for footer_message.
120    pub template: Option<String>,
121
122    // Placement switches
123    pub header: Option<bool>,
124    pub footer: Option<bool>,
125
126    /// Message templates in a table: message.header/message.footer/message.both
127    pub message: Option<MessageConfig>,
128
129    /// CSS font size for the rendered footer text.
130    ///
131    /// Default: `"0.8em"`.
132    #[serde(rename = "font-size")]
133    pub font_size: Option<String>,
134
135    /// String separator inserted between elements (e.g., date and hash).
136    ///
137    /// Default: `" • "`.
138    pub separator: Option<String>,
139
140    /// Format string for the date component.
141    ///
142    /// Uses the [`chrono`] crate formatting syntax.
143    /// Default: `"%Y-%m-%d"`.
144    #[serde(rename = "date-format")]
145    pub date_format: Option<String>,
146
147    /// Format string for the time component.
148    ///
149    /// Uses the [`chrono`] crate formatting syntax.
150    /// Default: `"%H:%M:%S"`.
151    #[serde(rename = "time-format")]
152    pub time_format: Option<String>,
153
154    pub timezone: Option<String>, // "local" | "utc" | "source" | "fixed:+01:00" | "rfc3339"
155    pub datetime_format: Option<String>, // optional: if set, overrides date/time format join
156    pub show_offset: Option<bool>, // optional: if true and no %z/%:z/%Z, append %:z
157
158    /// Git branch from which to retrieve commit history.
159    ///
160    /// Default: `"main"`.
161    pub branch: Option<String>,
162
163    /// Flexible align
164    /// - align = "center"
165    /// - align.header = "left", align.footer = "right"
166    /// - [preprocessor.gitinfo.align] both = "center"
167    pub align: Option<AlignSetting>,
168
169    /// CSS option to adjust margin between body and footer
170    pub margin: Option<MarginConfig>,
171
172    // explicit tag override (if set, use this instead of auto-detect)
173    pub tag: Option<String>,
174
175    /// CSS option provides a hyperlink to the respective branch and commit  
176    /// in the footer
177    ///
178    /// Options: "true | false"
179    /// Default: `false`.
180    pub hyperlink: Option<bool>,
181
182    /// Git Contributor switch
183    pub contributors: Option<bool>,
184
185    /// Optional title for the contributors block.
186    ///
187    /// Default: "Contributors:"
188    #[serde(rename = "contributors-title")]
189    pub contributors_title: Option<String>,
190
191    /// Optional message that can be set under the title
192    ///
193    /// Default: ""
194    #[serde(rename = "contributors-message")]
195    pub contributors_message: Option<String>,
196
197    /// Where to source contributors from.
198    ///
199    /// Options: "git" (default), "file", "inline"
200    ///
201    /// - git: derive from `git shortlog -sne --all`
202    /// - file: read from CONTRIBUTORS.md (or contributors-file)
203    /// - inline: only `{% contributors a b %}` tokens are used
204    #[serde(rename = "contributors-source")]
205    pub contributors_source: Option<ContributorsSource>,
206
207    /// Optional path to a Markdown file containing one GitHub username per line.
208    /// Relative paths are resolved from the Git repository root. When set,
209    /// this overrides contributors-source (including Git shortlog).
210    #[serde(rename = "contributor-file")]
211    pub contributor_file: Option<String>,
212
213    /// Legacy file path used when contributors-source = "file".
214    /// Relative paths are resolved from the Git repository root.
215    /// Default: "CONTRIBUTORS.md"
216    #[serde(rename = "contributors-file")]
217    pub contributors_file: Option<String>,
218
219    /// List of contributor author names to exclude.
220    ///
221    /// Matches against the git author name (treated as GitHub username).
222    ///
223    /// Example:
224    /// contributors-exclude = ["github-actions[bot]", "template-author"]
225    #[serde(rename = "contributors-exclude")]
226    pub contributors_exclude: Option<Vec<String>>,
227
228    /// Maximum number of contributor avatars shown before collapsing into a "Show all" expander.
229    /// Default: 24
230    #[serde(rename = "contributors-max-visible")]
231    pub contributors_max_visible: Option<usize>,
232}
233
234/// Load and deserialize the `[preprocessor.gitinfo]` table from `book.toml`.
235///
236/// This function reads configuration values from the mdBook configuration
237/// tree and deserializes them into [`GitInfoConfig`].
238///
239/// If the `[preprocessor.gitinfo]` section is missing, default values are
240/// returned. Invalid configuration values result in an error.
241///
242/// # Arguments
243///
244/// * `ctx` — The [`PreprocessorContext`] provided by `mdbook-preprocessor`,
245///   containing the parsed `book.toml` configuration.
246///
247/// # Errors
248///
249/// Returns an [`Error`] if the configuration section exists but cannot be
250/// deserialized into [`GitInfoConfig`].
251///
252/// # Examples
253///
254/// ```no_run
255/// use mdbook_preprocessor::PreprocessorContext;
256/// use mdbook_gitinfo::config::load_config;
257///
258/// fn example(ctx: &PreprocessorContext) -> Result<(), mdbook_preprocessor::errors::Error> {
259///     let cfg = load_config(ctx)?;
260///
261///     if let Some(template) = cfg.template {
262///         println!("Using template: {}", template);
263///     }
264///
265///     Ok(())
266/// }
267/// ```
268pub fn load_config(ctx: &PreprocessorContext) -> Result<GitInfoConfig, Error> {
269    ctx.config
270        .get::<GitInfoConfig>("preprocessor.gitinfo")?
271        .ok_or_else(|| Error::msg("Missing or invalid [preprocessor.gitinfo] config"))
272}
273
274#[cfg(test)]
275mod tests {
276    use super::*;
277    use mdbook_preprocessor::{PreprocessorContext, config::Config};
278    use std::path::PathBuf;
279
280    fn ctx(toml_str: &str) -> PreprocessorContext {
281        let parsed: toml::Value = toml::from_str(toml_str).unwrap();
282
283        let mut config = Config::default();
284        // Config::set returns Result in mdBook 0.5.x
285        config.set("preprocessor.gitinfo", parsed).unwrap();
286
287        // PreprocessorContext is non_exhaustive; use constructor
288        PreprocessorContext::new(PathBuf::from("."), config, "html".to_string())
289    }
290
291    #[test]
292    fn parses_legacy_align() {
293        let c = load_config(&ctx(r#"align = "left""#)).unwrap();
294        match c.align.unwrap() {
295            AlignSetting::One(s) => assert_eq!(s, "left"),
296            _ => panic!("expected One"),
297        }
298    }
299
300    #[test]
301    fn parses_split_align() {
302        let c = load_config(&ctx(r#"
303            [align]
304            both = "center"
305            header = "left"
306        "#))
307        .unwrap();
308
309        match c.align.unwrap() {
310            AlignSetting::Split {
311                header,
312                footer,
313                both,
314            } => {
315                assert_eq!(header.as_deref(), Some("left"));
316                assert_eq!(footer, None);
317                assert_eq!(both.as_deref(), Some("center"));
318            }
319            _ => panic!("expected Split"),
320        }
321    }
322
323    #[test]
324    fn message_resolution_parses() {
325        let c = load_config(&ctx(r#"
326            [message]
327            both = "D: {{date}}"
328            header = "H: {{date}}"
329        "#))
330        .unwrap();
331
332        assert_eq!(c.message.unwrap().header.unwrap(), "H: {{date}}");
333    }
334}