How vhquan/ssg works
Project Type and Purpose
• This is a modern, lightweight static site generator written in Rust. Its purpose is to take markdown content from the resources provided by the user, process it (applying syntax highlighting, templating, and markdown conversion), and generate a static HTML website complete with CSS styling.
• The README underlines features like tag-based content organization, responsive design, and code syntax highlighting, which point to a system that processes content and renders it through templates.
Analyzing the File Structure
• Top-level files include the Cargo configuration files (Cargo.toml and Cargo.lock) and the README. This denotes a typical Rust project.
• The src/ directory holds the core logic with modules like:
• generator.rs – likely orchestrates the generation process from markdown to HTML.
• markdown.rs – handles markdown parsing.
• models.rs – contains data structures.
• server.rs – probably provides functionality to run a local development server, allowing for live preview.
• utils.rs – contains helper functions.
• lib.rs and main.rs – expose library functions and define the executable entry point respectively.
• The templates/ directory contains Tera HTML templates which the generator uses to create the website pages.
• The style/ directory contains the CSS files.
• The resources/ directory contains the markdown and other source content from which the site is built.
• Although a static output folder (“static/”) is mentioned in the README, it isn’t directly seen in the file tree. It could be generated at runtime or simply not tracked in version control.
Main Components
a. Input/Content Layer:
• Resources/ directory as the source of markdown content.
b. Processing Layer:
• A block representing the core of the static site generator that includes:
• Markdown Parsing (handled in markdown.rs)
• Content Modeling (using models.rs)
• Code Syntax Highlighting (integrated via Highlight.js in the templates)
• Generation Logic (in generator.rs)
• Templating Integration (using the Tera engine in connection with templates/)
• A connection showing that content flows from the resources folder through the generator’s logic.
c. Output/Presentation Layer:
• A block for the templates/ and style/ directories:
• Templates are combined with the processed data to create HTML.
• The style folder supplies the CSS, and Highlight.js (referenced in base.html) provides syntax highlighting.
d. serving & Development:
• Server component (from server.rs) as a mechanism to host the generated site locally for development purposes, showing how it sits between the Generation Logic and the user’s browser.
Architectural Relationships & Patterns
• The separation between content input (resources/) and presentation (templates/ and style/) emphasizes a clear separation-of-concerns, similar to MVC principles:
• The “model” is represented by the data structures in models.rs.
• The “view” is handled via the Tera templates and CSS styles.
• The “controller” aspect is performed via the generator and server modules that orchestrate the flow.
• The build process (via Cargo and command-line instructions: “cargo run -- build” or “cargo run -- serve”) should be shown as the initial trigger that activates the core processing logic.