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", "^temp.*"] # Regex patterns to exclude files/dirs (default: [])
69//! exclude_defaults = true # Exclude README.md, LICENSE.md, etc. (default: true)
70//!
71//! [highlight]
72//! names = ["John Doe", "Jane Doe"] # Names to highlight (default: [])
73//! class = "me" # CSS class for highlights (default: "me")
74//!
75//! [templates]
76//! blog = "post.html" # Section -> template mapping
77//! projects = "project.html" # (default: uses {section}.html or post.html)
78//!
79//! [permalinks]
80//! blog = "/:year/:month/:slug/" # Section -> URL pattern
81//! projects = "/:slug/" # Placeholders: :year :month :day :slug :title :section
82//!
83//! [encryption]
84//! password_command = "pass show site" # Command to get password (optional)
85//! password = "secret" # Raw password (optional, less secure)
86//! # Priority: SITE_PASSWORD env > command > password
87//!
88//! [graph]
89//! enabled = true # Enable graph generation (default: true)
90//! template = "graph.html" # Graph page template (default: "graph.html")
91//! path = "graph" # URL path (default: "graph" -> /graph/)
92//!
93//! [rss]
94//! enabled = true # Enable RSS generation (default: true)
95//! filename = "rss.xml" # Output filename (default: "rss.xml")
96//! sections = ["blog"] # Sections to include (default: [] = all)
97//! limit = 20 # Max items (default: 20)
98//! exclude_encrypted_blocks = false # Exclude posts with :::encrypted (default: false)
99//!
100//! [text]
101//! enabled = false # Enable plain text generation (default: false)
102//! sections = ["blog"] # Sections to include (default: [] = all)
103//! exclude_encrypted = false # Exclude encrypted posts (default: false)
104//! include_home = true # Include home page as index.txt (default: true)
105//! ```
106//!
107//! ## Root Pages
108//!
109//! Markdown files at the content root (besides the home page) are processed as
110//! standalone pages. For example, `404.md` becomes `404.html`:
111//!
112//! ```yaml
113//! ---
114//! title: "404 - Page Not Found"
115//! template: "error.html"
116//! ---
117//!
118//! # Page Not Found
119//! The page you're looking for doesn't exist.
120//! ```
121//!
122//! Default excluded files (disable with `exclude_defaults = false`):
123//! - README.md, LICENSE.md, CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md
124//! - Hidden files (starting with `.`)
125//!
126//! ## Frontmatter
127//!
128//! Post frontmatter options (YAML or TOML):
129//!
130//! ```yaml
131//! ---
132//! title: "Post Title" # Required
133//! description: "Description" # Optional
134//! date: 2024-01-15 # Optional (YAML date or string)
135//! tags: ["tag1", "tag2"] # Optional
136//! draft: false # Optional (default: false, excluded from build)
137//! image: "/static/post.png" # Optional: OG image
138//! template: "custom.html" # Optional: Override template
139//! slug: "custom-slug" # Optional: Override URL slug
140//! permalink: "/custom/url/" # Optional: Full URL override
141//! encrypted: false # Optional: Encrypt entire post
142//! password: "post-secret" # Optional: Post-specific password
143//! ---
144//! ```
145//!
146//! ## Partial Encryption
147//!
148//! Use `:::encrypted` blocks for partial content encryption:
149//!
150//! ```markdown
151//! Public content here.
152//!
153//! :::encrypted
154//! This content is encrypted with the global/post password.
155//! :::
156//!
157//! :::encrypted password="custom"
158//! This block has its own password.
159//! :::
160//! ```
161//!
162//! ## Template Variables
163//!
164//! ### Home Template (`home.html`)
165//! - `site` - Site config (title, description, base_url, author)
166//! - `page` - Page info (title, description, url, image)
167//! - `sections` - All sections with posts (`sections.blog.posts`)
168//! - `content` - Rendered markdown content
169//!
170//! ### Post Template (`post.html`)
171//! - `site` - Site config
172//! - `post` - Post info (title, url, date, tags, reading_time, etc.)
173//! - `page` - Page info for head.html compatibility
174//! - `content` - Rendered markdown content
175//! - `backlinks` - Posts linking to this post (url, title, section)
176//! - `graph` - Local graph data (nodes, edges) for visualization
177//!
178//! ### Graph Template (`graph.html`)
179//! - `site` - Site config
180//! - `page` - Page info
181//! - `graph` - Full graph data (nodes, edges)
182//!
183//! ## Modules
184//!
185//! - [`config`] - Configuration loading and structures
186//! - [`content`] - Content discovery and post/page models
187//! - [`markdown`] - Markdown processing pipeline
188//! - [`templates`] - Tera template rendering
189//! - [`encryption`] - AES-GCM encryption for protected content
190//! - [`links`] - Link graph and backlink generation
191//! - [`rss`] - RSS feed generation
192//! - [`text`] - Plain text output for curl-friendly access
193//! - [`assets`] - CSS building and image optimization
194//! - [`build`] - Main build orchestrator
195
196pub mod assets;
197pub mod build;
198pub mod config;
199pub mod content;
200pub mod encryption;
201pub mod git;
202pub mod links;
203pub mod markdown;
204pub mod rss;
205pub mod templates;
206pub mod text;
207pub mod watch;