Using the BlogSite Package

The MyLittleContentEngine.BlogSite package provides a complete blog site solution with minimal setup. It includes all the components, layouts, and styling needed to create a professional blog with customizable branding, RSS feeds, and social media integration.

Important

While functional, the BlogSite package drives the documentation for my personal blog. It can and will change as this site changes. It is better suited as inspiration or proof-of-concepts than a blog you want total control over.

Tip

For documentation-style sites, see Using DocSite. For custom styling options, see Configure Custom Styling.

What You'll Build

You'll create a blog site with:

A nice little blog layout with posts and archives
Individual blog post pages with metadata
Tag-based organization and filtering
RSS feed generation
Responsive design with dark/light mode
Social media integration
A bit of custom branding and styling

1
Create a New Blazor Project

Start by creating a new empty Blazor Server project:
```
dotnet new blazorserver-empty -n MyBlogSite
cd MyBlogSite
```
2
Add the BlogSite Package

Add the BlogSite package reference to your project:
```
dotnet add package MyLittleContentEngine.BlogSite
```
This package includes all the dependencies you need:
- MyLittleContentEngine - Core content management functionality
- MyLittleContentEngine.UI - UI components for blogs
- MyLittleContentEngine.MonorailCss - CSS framework for styling
- Mdazor - Markdown rendering for Blazor

Configure the BlogSite

Replace the content of Program.cs with the following minimal configuration:

using MyLittleContentEngine.BlogSite;
  
var builder = WebApplication.CreateBuilder(args);
  
builder.Services.AddBlogSite(_ => new BlogSiteOptions
{
    ApplicationArgs = args,
    SiteTitle = "My Blog",
    Description = "A blog about my adventures in coding",
});
  
var app = builder.Build();
  
app.UseBlogSite();
  
await app.RunBlogSiteAsync(args);

This minimal setup provides a complete blog site with default styling and layout.

4
Create the Content Structure

Create the blog content directory structure:
```
mkdir -p Content/Blog
```
The BlogSite package expects your blog posts to be in the Content/Blog directory by default.

Write Your First Blog Post

Create your first blog post at Content/Blog/2024/01/welcome-to-my-blog.md:

mkdir -p Content/Blog/2024/01

I like to put my blog posts in a year/month folder structure, but you can use any structure you want.

---
title: "Welcome to My Blog"
description: "My first blog post using MyLittleContentEngine"
published: 2024-01-15
tags: ["blogging", "getting-started"]
---

# Welcome to My Blog

This is my first blog post using MyLittleContentEngine! I'm excited to share my thoughts and experiences.

## What You Can Expect

- Regular updates about my coding journey
- Tips and tricks I've learned
- Project showcases
- Technical deep-dives

Stay tuned for more content!

Customize Your Blog

You can customize various aspects of your blog by modifying the options in Program.cs:

using MonorailCss;
using MyLittleContentEngine.BlogSite;
  
var builder = WebApplication.CreateBuilder(args);
  
builder.Services.AddBlogSite(_ => new BlogSiteOptions
{
    ApplicationArgs = args,
    // Basic site information
    SiteTitle = "My Coding Blog",
    Description = "Adventures in software development",
    CanonicalBaseUrl = "https://myblog.example.com",
  
    // Styling and branding
    PrimaryHue = 250, // Purple theme (0-360)
    BaseColorName = ColorNames.Slate,
    DisplayFontFamily = "Inter",
    BodyFontFamily = "Inter",
  
    // Blog configuration
    AuthorName = "Your Name",
    AuthorBio = "Software developer passionate about clean code",
    EnableRss = true,
    EnableSitemap = true,
  
    // Navigation links
    MainSiteLinks = [
        new HeaderLink("About", "/about"),
        new HeaderLink("Contact", "/contact")
    ],
  
    // Advanced customization
    ExtraStyles = """
        .blog-header {
            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
        }
        """
});
  
var app = builder.Build();
app.UseBlogSite();
await app.RunBlogSiteAsync(args);

For social media features, you can add social links and project showcases:

builder.Services.AddBlogSite(_ => new BlogSiteOptions
{
    ApplicationArgs = args,
    SiteTitle = "My Coding Blog",
    Description = "Adventures in software development",
  
    // Social media links
    Socials = [
        new SocialLink(
            Icon: SocialIcons.BlueskyIcon,
            Url: "https://bsky.app/yourusername"
        ),
        new SocialLink(
            Icon: SocialIcons.GithubIcon,
            Url: "https://github.com/yourusername"
        )
    ],
  
    // Project showcase
    MyWork = [
        new Project(
            Title: "Awesome Library",
            Description: "A useful library for developers",
            Url: "https://github.com/yourusername/awesome-library"
        ),
        new Project(
            Title: "Cool App",
            Description: "An innovative web application",
            Url: "https://coolapp.example.com"
        )
    ],
  
    // Custom hero content for home page
    HeroContent = new HeroContent(
        Title: "Welcome to My Blog",
        Description: "Sharing my journey in software development"
    )
});

Add Custom HTML and Fonts

For advanced customization, you can add custom HTML to the head section:

builder.Services.AddBlogSite(_ => new BlogSiteOptions
{
    ApplicationArgs = args,
    SiteTitle = "My Blog",
    Description = "A blog about coding",
  
    // Custom HTML for head section
    AdditionalHtmlHeadContent = """
        <link rel="preconnect" href="https://fonts.googleapis.com">
        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
        <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
        <meta name="author" content="Your Name">
        """
});

9
Configure File Watching for Development

Add the following to your .csproj file to enable hot reload during development:
```
<ItemGroup>
    <Watch Include="Content\**\*.*"/>
</ItemGroup>
```
10
Test Your Blog Site

Run your site in development mode:
```
dotnet watch
```
Navigate to https://localhost:5001 to see your blog in action!

While the page is open, try editing your blog post. You should see the changes reflected immediately without needing to restart the server.

Blog Post Front Matter

Your blog posts support rich metadata in the front matter. The BlogSite package uses BlogSiteFrontMatter which includes:

---
title: "My Post Title"
description: "A brief description of the post"
author: "Author Name"
date: 2024-01-15
tags: ["tag1", "tag2", "tag3"]
series: "optional name of a series that this post is part of"
repository: "optional repository link"
uid: "unique-identifier-for-xref-links"
is_draft: false
redirect_url: "optional-redirect-target"
---

Front Matter Properties

title: The title of the blog post (required)
description: A brief description for SEO and summaries (required)
author: Author name for the post
date: Publication date (defaults to current time)
tags: Array of tags for categorization
series: Optional series name for grouping related posts
repository: Optional repository or project link
uid: Unique identifier for cross-referencing
is_draft: Set to true to exclude from generation
redirect_url: Optional URL to redirect this page to

Available Configuration Options

The BlogSiteOptions class provides many customization options:

Option	Type	Default	Description
`SiteTitle`	string	required	The title displayed in the header
`Description`	string	required	Site description for SEO
`ApplicationArgs`	string[]	required	Command line arguments for BaseUrl handling
`PrimaryHue`	int	250	Primary color hue (0-360)
`BaseColorName`	string	"Slate"	Base color palette name
`CanonicalBaseUrl`	string?	null	Canonical URL for SEO and RSS
`MainSiteLinks`	HeaderLink[]	[]	Navigation links in header/footer
`ContentRootPath`	string	"Content"	Path to content directory
`BlogContentPath`	string	"Blog"	Path to blog content (relative to ContentRootPath)
`BlogBaseUrl`	string	"/blog"	Base URL for blog posts
`TagsPageUrl`	string	"/tags"	URL for the tags page
`ExtraStyles`	string?	null	Additional CSS styles
`HeroContent`	HeroContent?	null	Custom hero content for home page
`DisplayFontFamily`	string?	null	Custom font family for display elements
`BodyFontFamily`	string?	null	Custom font family for body text
`AdditionalHtmlHeadContent`	string?	null	Custom HTML for head section
`AdditionalRoutingAssemblies`	Assembly[]	[]	List of additional assemblies to scan for routing
`AuthorName`	string?	null	Author name for the blog
`AuthorBio`	string?	null	Author bio for the blog
`EnableRss`	bool	true	Enable RSS feed generation
`EnableSitemap`	bool	true	Enable sitemap generation
`MyWork`	Project[]	[]	Projects to include in sidebar
`Socials`	SocialLink[]	[]	Social media links
`SolutionPath`	string?	null	Path to solution file for API docs
`SocialMediaImageUrlFactory`	Func<MarkdownContentPage, string>?	null	Function to generate social media image URLs

Next Steps

The BlogSite package allows you to get up and running quickly, but there are no promises made that the design or functionality of the site will remain consistent. It's what drives my personal blog, so as my whims change so will the package. Use it for quick proof-of-concepts, demos, or inspiration for your own blog using the MyLittleContentEngine services directly.

What You'll Build

Create a New Blazor Project

Add the BlogSite Package

Configure the BlogSite

Create the Content Structure