Get Started

Install rust, leptosfmt and cargo leptos and install the node + packges

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install sqlx-cli --no-default-features --features native-tls,postgres
cargo install leptosfmt
cargo binstall cargo-leptos --version 0.2.34 --force

## if you somehow dont have node installed; use your package manager or go look at their website
npm install

## assuming a postgres server is running, execute the following to initialize a new database for the server to use.
# Before running the below commands you will need to update the .env file to use your postgres user and password
cargo sqlx prepare
cargo sqlx database create
cargo sqlx migrate run

## (optional) add sample data to the database, check the Database section below.

## generate styles
npx postcss ./style/ --dir ./public/

## run the server!
cargo leptos watch

Styles/CSS

Normally Leptos handles styling through a provided tailwind file. This project uses a different method allowing us to splitting up the css per page. If you run the site and styling is missing run the below command.

npx postcss ./style/ --dir ./public/

Database

The database schema is located in migrations/20251012220332_setup.sql.

To make changes you create a migration file...

Example: cargo sqlx migration add changed-column-names

a new file will appear in the migrations folder, make your updates/changes inside of it. Then run...

cargo sqlx migrate run

Adding data

Add any new thumbnails into the BLOG_RESOURCE_FOLDER folder. Additionally blog files are read from BLOG_FOLDER so place any new ones there. After this you would insert data into the db for the corrosponding files. See sample data for more info

Sample data

-- Check './posts' and you will find 'fuller-test.md'
-- The thumbnail will be found in './resources/thumbnails'
INSERT INTO blogs (
    title,
    created,
    description,
    image_name,
    file_name,
    slug
)
VALUES (
    'First Project',
    '2025-09-28',
    'A blog description.',
    'windows-dev.webp',
    'fuller-test.md',
    'example-project'
);

-- For projects, just place the picture in the root of './resources'
INSERT INTO projects (
    title,
    description,
    image_name,
    url,
    created,
    live,
    released
)
VALUES (
    'Project One',
    'Project description',
    'WinAlpha.webp',
    'https://fff-d.com',
    '2025-09-28',
    true,
    true
);

Configuration

The server can be configured with the below environment variables.

export DATABASE_URL="postgres://postgres:password@localhost:5432/simple_blog"
export BLOG_FOLDER="posts"
export BLOG_RESOURCE_FOLDER="resources"

Notes

If sqlx is causing issues update the .env file to use your databases connection string, and make sure to run cargo sqlx prepare after.

The intended use of this is inside of a docker container which you would use environment variables with to specify some database, and volume/folders to use.

Viewing blogs

Blogs are loaded based on the slug value provided in the database.

Caching behavior

The server syncs with the database every 5 minutes. If new content is detected (tags, blogs, or projects), any related cached HTML/markdown will be updated.

Blogs

If the blog markdown is already cached (as in processed to HTML), it's served immediately
If not cached, the markdown is:
- Processed on-demand and served to the user
- Added to the cache for subsequent requests
The server compares the checksum of the cached markdown against the actual file contents including the view count from the database
- flow:
  - look for blog file in BLOG_FOLDER
  - process the markdown to HTML
  - update the viewcount element in the HTML
  - update the checksum (at this point we compare checksum agaisnt the cached version)
By default, a cached blog is updated when a unique view is recorded
- only the specific section containing the view count is updated

Environment variable fallback values

Environment Variable	Fallback Value	Description
`BLOG_FOLDER`	`./posts`	Directory containing blog posts
`BLOG_RESOURCES`	`./resources`	Directory containing project thumbnails at the root and blog thumbnails in a child directory `thumbnails`

tadghh/simple-rust-blog