rs_web/lib.rs
1//! # rs-web - Static Site Generator
2//!
3//! A fast, opinionated static site generator built in Rust with support for:
4//!
5//! - **Markdown processing** with syntax highlighting, external link handling
6//! - **Content encryption** (full post or partial `:::encrypted` blocks)
7//! - **Link graph** with backlinks and visualization (Obsidian-style)
8//! - **RSS feed** generation with section filtering
9//! - **Parallel processing** for fast builds
10//!
11//! ## Quick Start
12//!
13//! ```bash
14//! # Build the site
15//! rs-web build
16//!
17//! # Build to custom output directory
18//! rs-web build --output public
19//!
20//! # Watch for changes and rebuild incrementally
21//! rs-web build --watch
22//!
23//! # Enable debug logging
24//! rs-web --debug build
25//!
26//! # Set specific log level (trace, debug, info, warning, error)
27//! rs-web --log-level trace build
28//!
29//! # Or use environment variable
30//! RS_WEB_LOG_LEVEL=debug rs-web build
31//! ```
32//!
33//! ## Configuration
34//!
35//! Configure via `config.toml`:
36//!
37//! ### Required Settings
38//!
39//! ```toml
40//! [site]
41//! title = "My Site" # Site title
42//! description = "Site description" # Site description
43//! base_url = "https://example.com" # Base URL (no trailing slash)
44//! author = "Your Name" # Author name
45//!
46//! [seo]
47//! twitter_handle = "@username" # Optional: Twitter handle
48//! default_og_image = "/static/og.png" # Optional: Default OG image
49//!
50//! [build]
51//! output_dir = "dist" # Output directory
52//! minify_css = true # Default: true
53//!
54//! [images]
55//! quality = 85.0 # WebP quality (default: 85.0)
56//! scale_factor = 1.0 # Image scale (default: 1.0)
57//! ```
58//!
59//! ### Optional Settings (have defaults)
60//!
61//! ```toml
62//! [paths]
63//! content = "content" # Content directory (default: "content")
64//! styles = "styles" # Styles directory (default: "styles")
65//! static_files = "static" # Static files (default: "static")
66//! templates = "templates" # Templates (default: "templates")
67//! home = "index.md" # Home page file (default: "index.md")
68//! exclude = ["drafts", "private"] # Directories to exclude (default: [])
69//!
70//! [highlight]
71//! names = ["John Doe", "Jane Doe"] # Names to highlight (default: [])
72//! class = "me" # CSS class for highlights (default: "me")
73//!
74//! [templates]
75//! blog = "post.html" # Section -> template mapping
76//! projects = "project.html" # (default: uses {section}.html or post.html)
77//!
78//! [permalinks]
79//! blog = "/:year/:month/:slug/" # Section -> URL pattern
80//! projects = "/:slug/" # Placeholders: :year :month :day :slug :title :section
81//!
82//! [encryption]
83//! password_command = "pass show site" # Command to get password (optional)
84//! password = "secret" # Raw password (optional, less secure)
85//! # Priority: SITE_PASSWORD env > command > password
86//!
87//! [graph]
88//! enabled = true # Enable graph generation (default: true)
89//! template = "graph.html" # Graph page template (default: "graph.html")
90//! path = "graph" # URL path (default: "graph" -> /graph/)
91//!
92//! [rss]
93//! enabled = true # Enable RSS generation (default: true)
94//! filename = "rss.xml" # Output filename (default: "rss.xml")
95//! sections = ["blog"] # Sections to include (default: [] = all)
96//! limit = 20 # Max items (default: 20)
97//! exclude_encrypted_blocks = false # Exclude posts with :::encrypted (default: false)
98//!
99//! [text]
100//! enabled = false # Enable plain text generation (default: false)
101//! sections = ["blog"] # Sections to include (default: [] = all)
102//! exclude_encrypted = false # Exclude encrypted posts (default: false)
103//! include_home = true # Include home page as index.txt (default: true)
104//! ```
105//!
106//! ## Frontmatter
107//!
108//! Post frontmatter options (YAML or TOML):
109//!
110//! ```yaml
111//! ---
112//! title: "Post Title" # Required
113//! description: "Description" # Optional
114//! date: 2024-01-15 # Optional (YAML date or string)
115//! tags: ["tag1", "tag2"] # Optional
116//! draft: false # Optional (default: false, excluded from build)
117//! image: "/static/post.png" # Optional: OG image
118//! template: "custom.html" # Optional: Override template
119//! slug: "custom-slug" # Optional: Override URL slug
120//! permalink: "/custom/url/" # Optional: Full URL override
121//! encrypted: false # Optional: Encrypt entire post
122//! password: "post-secret" # Optional: Post-specific password
123//! ---
124//! ```
125//!
126//! ## Partial Encryption
127//!
128//! Use `:::encrypted` blocks for partial content encryption:
129//!
130//! ```markdown
131//! Public content here.
132//!
133//! :::encrypted
134//! This content is encrypted with the global/post password.
135//! :::
136//!
137//! :::encrypted password="custom"
138//! This block has its own password.
139//! :::
140//! ```
141//!
142//! ## Template Variables
143//!
144//! ### Home Template (`home.html`)
145//! - `site` - Site config (title, description, base_url, author)
146//! - `page` - Page info (title, description, url, image)
147//! - `sections` - All sections with posts (`sections.blog.posts`)
148//! - `content` - Rendered markdown content
149//!
150//! ### Post Template (`post.html`)
151//! - `site` - Site config
152//! - `post` - Post info (title, url, date, tags, reading_time, etc.)
153//! - `page` - Page info for head.html compatibility
154//! - `content` - Rendered markdown content
155//! - `backlinks` - Posts linking to this post (url, title, section)
156//! - `graph` - Local graph data (nodes, edges) for visualization
157//!
158//! ### Graph Template (`graph.html`)
159//! - `site` - Site config
160//! - `page` - Page info
161//! - `graph` - Full graph data (nodes, edges)
162//!
163//! ## Modules
164//!
165//! - [`config`] - Configuration loading and structures
166//! - [`content`] - Content discovery and post/page models
167//! - [`markdown`] - Markdown processing pipeline
168//! - [`templates`] - Tera template rendering
169//! - [`encryption`] - AES-GCM encryption for protected content
170//! - [`links`] - Link graph and backlink generation
171//! - [`rss`] - RSS feed generation
172//! - [`text`] - Plain text output for curl-friendly access
173//! - [`assets`] - CSS building and image optimization
174//! - [`build`] - Main build orchestrator
175
176pub mod assets;
177pub mod build;
178pub mod config;
179pub mod content;
180pub mod encryption;
181pub mod links;
182pub mod markdown;
183pub mod rss;
184pub mod templates;
185pub mod text;
186pub mod watch;