perga 0.1.5

A terminal Markdown browser with a persistent file tree, tabs, wiki-links and backlinks
Documentation
//! Serde structures and built-in defaults for every configuration key.
//!
//! The full five-layer precedence chain is assembled in [`super`]. This module
//! only describes the shape of the configuration and what each key defaults to.

use serde::Deserialize;

use crate::ui::sidebar::SidebarMode;

/// Presentation and chrome. The `[ui]` table.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct UiConfig {
    /// Whether the sidebar starts visible.
    pub sidebar_visible: bool,
    /// The sidebar's width in columns.
    pub sidebar_width: u16,
    /// Which sidebar mode is showing on startup.
    pub sidebar_default_mode: SidebarMode,
    /// Show the tab bar even with a single tab open.
    pub always_show_tabs: bool,
    /// Show line numbers in the viewport.
    pub show_line_numbers: bool,
    /// Show the `#` a heading is written with.
    ///
    /// On by default. With it off a heading is told from body text by its
    /// colour and weight alone, which is enough on a colour terminal and is
    /// not enough under `NO_COLOR`, where every level collapses to bold.
    pub show_heading_markers: bool,
    /// Show the status bar.
    pub show_status_bar: bool,
    /// Lines scrolled per mouse wheel notch.
    pub mouse_scroll_lines: u16,
    /// Capture the mouse. Off leaves terminal text selection available.
    pub mouse: bool,
    /// Auto-hide the sidebar below this terminal width.
    pub narrow_threshold: u16,
}

impl Default for UiConfig {
    fn default() -> Self {
        UiConfig {
            sidebar_visible: true,
            sidebar_width: 32,
            sidebar_default_mode: SidebarMode::Files,
            always_show_tabs: false,
            show_line_numbers: false,
            show_heading_markers: true,
            show_status_bar: true,
            mouse_scroll_lines: 3,
            mouse: true,
            narrow_threshold: 80,
        }
    }
}

/// How the files sidebar orders the entries in a directory.
///
/// Directories always come before files whatever this says; the key only
/// orders entries of the same kind.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum SortKey {
    /// Alphabetically, case-insensitively.
    #[default]
    Name,
    /// Most recently modified first.
    Mtime,
    /// Largest first.
    Size,
}

/// The vault tree. The `[files]` table.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct FilesConfig {
    /// Include dotted directories such as `.github` and `.claude`.
    ///
    /// On by default, deliberately: a dotted directory in a notes vault holds
    /// notes, and hiding it by default with no visible override is the
    /// behaviour this project exists to avoid.
    pub include_hidden: bool,
    /// Honour `.gitignore`, `.ignore`, and the global gitignore.
    pub respect_gitignore: bool,
    /// Show files that are not Markdown.
    pub show_all: bool,
    /// How entries within a directory are ordered.
    pub sort: SortKey,
    /// Reverse whatever order `sort` produces.
    pub sort_reverse: bool,
    /// Extensions treated as Markdown, without the leading dot.
    pub extensions: Vec<String>,
}

impl Default for FilesConfig {
    fn default() -> Self {
        FilesConfig {
            include_hidden: true,
            respect_gitignore: true,
            show_all: false,
            sort: SortKey::Name,
            sort_reverse: false,
            extensions: ["md", "markdown", "mdx"]
                .iter()
                .map(|s| (*s).to_string())
                .collect(),
        }
    }
}

impl FilesConfig {
    /// Whether a path's extension marks it as Markdown.
    pub fn is_markdown(&self, path: &std::path::Path) -> bool {
        let Some(extension) = path.extension().and_then(|e| e.to_str()) else {
            return false;
        };
        self.extensions
            .iter()
            .any(|known| known.eq_ignore_ascii_case(extension))
    }
}

/// The order wiki-link targets are looked up in. The `[wikilinks]` table's
/// `resolution` key.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum WikiResolutionOrder {
    /// An exact relative path first, then a filename search.
    #[default]
    PathFirst,
    /// A filename search first, then an exact relative path.
    FilenameFirst,
}

/// Wiki-links and the backlink index. The `[wikilinks]` table.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct WikiLinkConfig {
    /// Parse `[[Page]]` links and build the backlink index at all.
    pub enabled: bool,
    /// Extensions a page name is searched with, without the leading dot.
    pub extensions: Vec<String>,
    /// Which of the two resolution orders to use.
    pub resolution: WikiResolutionOrder,
    /// Build the index on startup rather than on first use.
    pub index_on_start: bool,
    /// Cache the index between runs.
    pub cache: bool,
    /// Where a file created from a broken wiki-link goes. Empty means the
    /// active document's own directory.
    pub new_file_dir: std::path::PathBuf,
}

impl Default for WikiLinkConfig {
    fn default() -> Self {
        WikiLinkConfig {
            enabled: true,
            extensions: ["md", "markdown"]
                .iter()
                .map(|s| (*s).to_string())
                .collect(),
            resolution: WikiResolutionOrder::default(),
            index_on_start: true,
            cache: true,
            new_file_dir: std::path::PathBuf::new(),
        }
    }
}

/// Theme selection. The `[theme]` table.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct ThemeConfig {
    /// `auto`, a built-in name, or the stem of a file in [`ThemeConfig::dir`].
    pub name: String,
    /// An extra theme directory. Empty means `$XDG_CONFIG_HOME/perga/themes`.
    pub dir: std::path::PathBuf,
    /// The `syntect` theme for fenced code blocks.
    pub code_theme: String,
}

impl Default for ThemeConfig {
    fn default() -> Self {
        ThemeConfig {
            name: "auto".to_string(),
            dir: std::path::PathBuf::new(),
            code_theme: "base16-ocean.dark".to_string(),
        }
    }
}

/// Project-wide search. The `[search]` table.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct SearchConfig {
    /// Stop after this many hits and say the results were cut short.
    pub max_results: usize,
    /// Treat a query as a regular expression by default.
    pub regex: bool,
    /// Case-insensitive unless the query contains an upper-case character.
    pub smart_case: bool,
    /// Search files that are not Markdown.
    pub all_files: bool,
}

impl Default for SearchConfig {
    fn default() -> Self {
        SearchConfig {
            max_results: 1_000,
            regex: false,
            smart_case: true,
            all_files: false,
        }
    }
}

/// Editing. The `[editor]` table.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct EditorConfig {
    /// The command `o` hands the file to. Empty means `$EDITOR`.
    ///
    /// This is the one key a vault-local `.perga.toml` may never set: it names
    /// a program to run, and a local config arrives with any cloned repository.
    /// See Section 10.
    pub external_command: String,
    /// How many columns a tab is.
    pub tab_size: u8,
    /// Insert spaces rather than a tab character.
    pub insert_spaces: bool,
    /// Soft-wrap in edit mode. Off by default: edit the real lines.
    pub wrap: bool,
    /// Save on leaving edit mode and on an interval.
    pub autosave: bool,
    /// How often autosave writes.
    pub autosave_interval_secs: u64,
    /// Show whitespace characters.
    pub show_whitespace: bool,
    /// Seed a new file with a frontmatter title.
    pub new_file_frontmatter: bool,
}

impl Default for EditorConfig {
    fn default() -> Self {
        EditorConfig {
            external_command: String::new(),
            tab_size: 4,
            insert_spaces: true,
            wrap: false,
            autosave: false,
            autosave_interval_secs: 30,
            show_whitespace: false,
            new_file_frontmatter: false,
        }
    }
}

/// Filesystem watching. The `[watch]` table.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct WatchConfig {
    /// Watch the vault for changes at all.
    pub enabled: bool,
    /// How long a burst of events is coalesced for.
    pub debounce_ms: u64,
}

impl Default for WatchConfig {
    fn default() -> Self {
        WatchConfig {
            enabled: true,
            debounce_ms: 200,
        }
    }
}

/// Session persistence. The `[session]` table.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct SessionConfig {
    /// Restore the previous session when perga is opened with no path.
    pub restore: bool,
    /// How many documents the recent list remembers.
    pub max_recent: usize,
}

impl Default for SessionConfig {
    fn default() -> Self {
        SessionConfig {
            restore: true,
            max_recent: 50,
        }
    }
}

/// Vault-wide behaviour. The `[general]` table.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct GeneralConfig {
    /// Directory opened when no `PATH` argument is given.
    pub start_path: std::path::PathBuf,
    /// Read `.perga.toml` from the vault root.
    pub allow_local_config: bool,
    /// Follow symlinks while walking the vault.
    ///
    /// Off by default: a vault with a symlink loop in it is not exotic, and a
    /// walker that follows links has to carry a device/inode set to survive
    /// one.
    pub follow_symlinks: bool,
    /// Hard wrap width; 0 fits the viewport.
    pub wrap: u16,
    /// Expand tabs in source to this many spaces when rendering.
    pub tab_width: u8,
}

impl Default for GeneralConfig {
    fn default() -> Self {
        GeneralConfig {
            start_path: std::path::PathBuf::from("."),
            allow_local_config: true,
            follow_symlinks: false,
            wrap: 0,
            tab_width: 4,
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn defaults_match_the_documented_configuration() {
        let ui = UiConfig::default();
        assert!(ui.sidebar_visible);
        assert_eq!(ui.sidebar_width, 32);
        assert_eq!(ui.sidebar_default_mode, SidebarMode::Files);
        assert!(!ui.always_show_tabs);
        assert!(ui.show_heading_markers);
        assert_eq!(ui.narrow_threshold, 80);
        assert_eq!(ui.mouse_scroll_lines, 3);
    }

    #[test]
    fn a_partial_table_keeps_the_other_defaults() {
        let ui: UiConfig = toml::from_str("sidebar_width = 40").unwrap();
        assert_eq!(ui.sidebar_width, 40);
        assert!(ui.sidebar_visible);
    }

    #[test]
    fn sidebar_mode_parses_from_its_lowercase_name() {
        let ui: UiConfig = toml::from_str(r#"sidebar_default_mode = "outline""#).unwrap();
        assert_eq!(ui.sidebar_default_mode, SidebarMode::Outline);
    }
}