Developer Reference
API & CLI Reference
Complete Rust library types, traits, configuration builders, and CLI subcommands.
1. Crate Overview & Re-Exports (nucleusflow)
The root nucleusflow module re-exports the primary pipeline types so applications can import them directly from nucleusflow::*:
| Symbol | Module Path | Description |
|---|---|---|
NucleusFlow | nucleusflow::NucleusFlow | Top-level pipeline orchestrator connecting content processing, template rendering, and HTML generation |
NucleusFlowConfig | nucleusflow::NucleusFlowConfig | Directory configuration (content_dir, output_dir, template_dir) for NucleusFlow |
ContentProcessor | nucleusflow::processors::markdown::MarkdownProcessor | Stage 1 CommonMark + GFM + YAML 1.2 frontmatter processor |
HandlebarsRenderer | nucleusflow::template::HtmlTemplateRenderer | Stage 2 thread-safe cached Handlebars template renderer |
HtmlGenerator | nucleusflow::generators::html::HtmlOutputGenerator | Stage 3 HTML5 validator, <meta> injector, and minifier |
FileContentProcessor | nucleusflow::process::FileContentProcessor | File-oriented content processor with path sanitization and extension checks |
TemplateRenderer | nucleusflow::template::TemplateRenderer | Trait for rendering named templates with JSON context values |
ConfigBuilder | nucleusflow::core::config::ConfigBuilder | Builder for multi-profile TOML and environment configuration |
ProcessingError | nucleusflow::core::error::ProcessingError | Unified error enum for all pipeline stages |
Full generated Rustdoc is available on docs.rs/nucleusflow.
2. Stage 1: Content Processing (nucleusflow::processors::markdown)
MarkdownProcessor (re-exported as ContentProcessor)
use ContentProcessor;
use Processor;
let processor = new
.with_toc
.with_sanitization
.with_custom_Metadata;
let html = processor.process?;
| Method | Signature | Behavior |
|---|---|---|
new() | pub fn new() -> Self | Creates a processor with GFM tables, footnotes, and strikethrough enabled |
with_toc() | pub fn with_toc(self) -> Self | Enables automatic <nav class="toc"> generation from document headings |
with_sanitization() | pub fn with_sanitization(self) -> Self | Enables HTML tag allowlist (ALLOWED_HTML_TAGS) and XSS pattern blocking |
with_options(opts) | pub fn with_options(self, options: Options) -> Self | Customizes pulldown_cmark::Options bitflags |
with_custom_Metadata(k, v) | pub fn with_custom_Metadata(self, key: String, value: String) -> Self | Attaches custom metadata key-value pairs |
process(&self, input) | fn process(&self, input: &str) -> Result<String, ProcessingError> | Validates size (<= 10 MB), extracts YAML frontmatter, renders Markdown, and sanitizes output |
3. Stage 2: Template Rendering (nucleusflow::template)
HtmlTemplateRenderer (re-exported as HandlebarsRenderer)
use ;
use UppercaseHelper;
use json;
let renderer = new
.with_template_dir
.with_strict_mode
.with_helper;
renderer.load_templates?;
let rendered = renderer.render?;
| Method | Signature | Behavior |
|---|---|---|
new() | pub fn new() -> Self | Initializes an Arc<RwLock<Handlebars>> registry with UppercaseHelper registered |
with_template_dir(dir) | pub fn with_template_dir<P: Into<PathBuf>>(self, dir: P) -> Self | Sets the directory used by load_templates() to scan .hbs files |
with_partial(name, content) | pub fn with_partial(self, name: String, content: String) -> Result<Self, ProcessingError> | Validates and registers a named Handlebars partial |
with_helper(name, helper) | pub fn with_helper(self, name: String, helper: Box<dyn TemplateHelper>) -> Self | Registers a custom TemplateHelper implementation |
with_strict_mode() | pub fn with_strict_mode(self) -> Self | Requires all referenced template variables to exist in the context JSON |
load_templates(&self) | pub fn load_templates(&self) -> Result<(), ProcessingError> | Recursively loads all .hbs files from template_dir into the cache |
register_template(&mut self, name, tpl) | fn register_template(&mut self, name: &str, template: &str) -> Result<(), ProcessingError> | Validates brace balance and compiles a template into the registry |
render(&self, name, data) | fn render(&self, template_name: &str, data: &Value) -> Result<String, ProcessingError> | Renders a cached template with a serde_json::Value context |
4. Stage 3: Output Generation (nucleusflow::generators::html)
HtmlOutputGenerator (re-exported as HtmlGenerator)
use HashMap;
use HtmlGenerator;
use Generator;
let mut meta = new;
meta.insert;
let generator = new
.with_minification
.with_meta_tags
.with_asset_dir;
let output = generator.generate?;
| Method | Signature | Behavior |
|---|---|---|
new() | pub fn new() -> Self | Creates an HTML5 generator with minification enabled by default |
with_minification() | pub fn with_minification(self) -> Self | Enables minify-html (HTML, CSS, and JS minification) |
without_minification() | pub fn without_minification(self) -> Self | Disables minification and enables indented pretty-printing |
with_asset_dir(dir) | pub fn with_asset_dir<P: Into<PathBuf>>(self, dir: P) -> Self | Sets the static asset directory and loads assets into the in-memory cache |
with_meta_tags(tags) | pub fn with_meta_tags(self, tags: HashMap<String, String>) -> Self | Injects HTML-escaped <meta> tags into <head> |
copy_assets_to(dir) | pub fn copy_assets_to<P: AsRef<Path>>(&self, output_dir: P) -> Result<(), ProcessingError> | Writes cached static assets to output_dir, rejecting .. path traversal |
generate(&self, content) | fn generate(&self, content: &str) -> Result<String, ProcessingError> | Validates HTML5 tag balance, injects <meta> tags, and minifies or formats |
5. Configuration & Core Traits (nucleusflow::core)
ConfigBuilder & Profile
use Duration;
use ;
let config = new
.with_file?
.with_env_prefix?
.with_auto_reload
.with_reload_interval
.with_max_file_size
.build?;
Core Traits (nucleusflow::core::traits)
Processor:fn process(&self, input: &str) -> Result<String, ProcessingError>andfn validate(&self, input: &str) -> Result<(), ProcessingError>.Transform:fn transform(&self, input: &str) -> Result<String, ProcessingError>andfn can_transform(&self, input_type: &str) -> bool.Generator:fn generate(&self, content: &str) -> Result<String, ProcessingError>andfn supported_formats(&self) -> Vec<&str>.Validator:fn validate(&self, content: &str, rules: &[ValidationRule]) -> Result<(), ProcessingError>.ProcessingContext:get_metadata(&self, key: &str),set_metadata(&mut self, key: String, value: String),get_options(&self) -> &ProcessingOptions.Shareable: Blanket trait providing.into_shared()(Arc<RwLock<Self>>) for anySend + Sync + 'staticcomponent.
ProcessingError Variants (nucleusflow::core::error)
| Variant | Trigger Condition |
|---|---|
MarkdownError(String) | Empty input, content exceeding 10 MB, or Markdown parse failure |
InvalidFrontmatter(String) | Empty frontmatter or invalid YAML 1.2 syntax |
HtmlSanitizationError(String) | Disallowed HTML tag or suspicious XSS attribute/URI pattern |
TemplateSyntaxError(String) | Unbalanced {{ / }} braces or invalid Handlebars syntax |
TemplateRenderError(String) | Missing template name or Handlebars evaluation error |
TemplateDataError(String) | Missing required variable in strict mode or non-object context |
InvalidHtmlError(String) | Mismatched closing HTML tag or unclosed non-void element |
ConfigValidationError(String) | Configuration file exceeding 1 MB or out-of-range budget parameter |
EnvVarError(String) | Disallowed environment variable name (PATH, HOME, USER, SHELL) |
AssetCopyError(String) | Path traversal attempt (..) or missing asset source directory |
6. CLI Reference (nucleusflow)
nucleusflow [SUBCOMMAND] [OPTIONS]
| Subcommand | Flags & Arguments | Defaults | Description |
|---|---|---|---|
new <name> | -t, --template <template> | blog (blog, docs, portfolio) | Scaffolds a new NucleusFlow project directory |
build | -c, --content-dir <DIR>-o, --output-dir <DIR>-t, --template-dir <DIR>-m, --minify--config <FILE> | contentpublictemplatesfalsenucleusflow.toml | Compiles Markdown content and Handlebars templates into static HTML |
serve | -p, --port <PORT>-w, --watch-d, --dir <DIR> | 3000falsepublic | Serves the generated static directory locally with optional live watching |