search

statiqdev / CleanBlog

A blogging theme for Statiq Web.
MIT License
53 stars 25 forks source link
hacktoberfest

readme

Clean Blog

This is a clean blogging theme adapted from https://github.com/StartBootstrap/startbootstrap-clean-blog, with some additional goodies of its own.

Minimum Statiq Web Version

This theme requires Statiq Web 1.0.0-beta.36 or later.

Using an earlier commit of the theme may allow the use of an earlier version of Statiq Web (look at the theme settings.yml file to determine the minimum Statiq Web version for a given version of the theme).

Installation

Statiq themes go in a theme folder alongside your input folder. If your site is inside a git repository, you can add the theme as a git submodule:

git submodule add https://github.com/statiqdev/CleanBlog.git theme

Alternatively, you can clone the theme directly:

git clone https://github.com/statiqdev/CleanBlog.git theme

Once inside the theme folder, Statiq will automatically recognize the theme.

If you're not going to modify theme files directly, you can leave the theme out of your repository and use the Devlead.Statiq package to automatically download it as you build your site. See this blog post for details.

Site Contents

You can add contents to your site using plain HTML and CSS, as well as any of the template languages supported by Statiq.Web. In the examples below, we will assume that you write your articles using Markdown, with front matter in YAML.

Home Page

By default, your blog's home page will be an archive, showing the latest blog posts in inverse chronological order.

Note that Statiq.Web does not generate archive pages if it finds no contents for them to index. In other words, the theme will have no home page until you add a blog post.

You can provide your own home page by adding an index.cshtml (or index.md) file in your input folder. Unless your custom home page is an archive too, it will be displayed regardless of the presence of any post.

Sidebar

On the right side of the list of posts, the default home page sports a vertical bar listing the ten most used tags. Clicking on any tag brings the user to the list of posts that have that tag, similarly to what happens of the "Tags" page.

All remaining space in the sidebar is yours! Just add a _sidebar.cshtml file in your input folder; it will be trated as a Razor partial and inserted just below the list of most used tags.

Blog Posts

Add your blog posts to a posts folder under your own input folder. An example post might be named input/posts/example.md and contain the following content:

Title: This Is An Example Post
Lead: Yay for examples!
Published: 12/13/2014
Tags:
  - Examples
  - Tag with spaces
---
This is my example blog post content.

The --- line separates the front matter, i.e. YAML code containing page-specific settings, from the actual body of the post. YAML syntax is widely known and is usually intuitive; however, if you need a quick tutorial or a refresher you may find this article useful.

As for the .md extension, it means that the article body is written with Markdown syntax. And yes, there's a quick guide for it, too. See also here for Markdown features specific to Statiq.Web.

Published Date

If you don't specify a Published date, Statiq will use the last modification date of the file. Since Git does not save and restore file times, you should always specify a Published date if you store your blog in a Git repository; otherwise, all your posts will appear to have been published at the date of checkout.

Tags

You may specify as many tags as you like, or even none. Of course, posts with no tags will not appear in the Tags archive.

Static pages

Static pages are different from blog posts, in that they have no taxonomy (published date, tags) and thus do not appear in archives. Their usual purpose is to provide information on a site-wide basis, for example an author's bio, portfolio, and/or resume; a privacy policy; a contact form; etc.

Add your static pages to a pages folder under your own input folder. An example page might be named input/pages/about.md and contain the following content:

NavbarTitle: About
Order: 1
Title: About me
Description: The life and times of James D. Author
---
Hi there, I'm James and this is my blog.

Short bio; why I opened a blog; miscellaneous yada yada.

Customization

This theme offers lots of customization options. Methods through which you can personalize your blog include:

NOTE: This theme uses Razor to build HTML pages and SASS to build CSS styles. You may want to familiarize with their syntax (besides, of course, HTML and CSS) before making additions and/or modifications.

The remainder of this section illustrates how to customize some specific areas of the theme. More exhaustive references for settings and placeholder files are in subsequent sections.

Basic Configuration

Here's an example of a settings.yml file:

# Hosting settings
Host: jamesdauthor.github.io # Host name - This example is for GitHub pages
LinksUseHttps: true # Whether to generate HTTPS links in archives etc. - usually true, of course

# Branding
SiteTitle: My awesome blog
SiteDescription: The blog no one but me was missing
Copyright: => @$"All content © {DateTime.Now.Year} James D. Author" # You can use C# expressions prefixed by =>

# Blog settings
DateTimeInputCulture: "" # This determines the expected format for Published dates in posts - Empty string means invariant culture (yyyy-MM-dd format)
DateTimeDisplayCulture: en-US # This determines the format for displayed dates, e.g. in post headers and archive pages
GenerateSearchIndex: true # Setting this to false disables both the search box in navigation bar and the search page

The Navigation Bar

The navigation bar is a series of links that appears at the top of every page of your blog on desktop browsers, or can be displayed by touching a "Menu" button in the top right corner on mobile browsers.

The navigation bar includes: links to all static pages (by default, see below), a "Posts" link to a historical archive of posts, and a "Tags" link to an index of all tags.

A search box is also included at the end of the navigation bar if search index generation is enabled.

Links To Static Pages

If you don't want a page to be linked in the navigation bar, add a ShowInNavbar: false setting in its front matter.

If you don't specify a value for NavbarTitle in a page, Title will be used as the link text.

Links are sorted by the value of their Order setting. Pages with Order greater than or equal to 100 will appear after "Posts" and "Tags".

Destination Paths

By default, posts and static pages are output using the same folder structure they were found in your posts and pages folders, respectively. If you want to modify that, you can use directory metadata to specify a different destination. If you combine that with computed values, you can programatically set the destination of your posts.

For example, the following in a _directory.yml file in the posts folder will result in outputting posts with a path of "yyyy/mm/post-title.html":

DestinationPath: => $"{Document.GetDateTime("Published").ToString("yyyy/MM")}/{Document.Destination.FileName}"

Keep in mind that what determines if a document is a post or a static page is its source location (unless, of course, you manually set IsPost or IsPage in front matter). You can go wild with computed destinations, even to the point where your resulting site has no posts or pages directory at all: the correct styles will still be applied to each post or static page, and of course all links (e.g. in archives and navigation bar) will point to your computed destinations.

Settings

Global

These can be set in a settings file (in addition to any of Statiq's settings and web settings).

It's also highly recommended to set Host and LinksUseHttps to match your hosting environment. This ensures that the RSS feeds and other artifacts that rely on absolute hosting information are correctly generated.

Page

These can be set in front matter, a sidecar file, etc. (in addition to any of Statiq's settings and web settings).

Post comments

These can be set in a settings file (in addition to any of Statiq's settings and web settings).

Currently, the only available comment engine is giscus.

You can interface to a comment engine of your choice without modifying this theme:

Giscus

giscus uses GitHub Discussions as comment storage.

The following settings must be set in your settings.yml file when CommentEngine is set to giscus:

To configure Giscus correctly in your blog, go to https://giscus.app and follow the configuration instructions, then copy and paste configuration values from the preconfigured <script> tag to your settings file.

Alternatively, or if you need to tweak some advanced Giscus setting, create a file named _post-comments-giscus.cshtml in your input folder and just copy the preconfigured script into it.

Calculated Settings

The following keys are calculated in settings.yml and can be overridden by providing new values in your settings or front matter or used from your own pages.

Partials

Replace or copy any of these Razor partials in your input folder to override sections of the site:

Sections

In addition to globally changing sections of the site using the partials above you can also add the following Razor sections to any given page to override them for that page (which will typically disable the use of the corresponding partial):

Styles

There are three distinct extensibility points for styles:

You will find the definitions of overridable Sass variables in the following files:

Porting From Wyam

This blogging theme is roughly compatible with the Wyam CleanBlog theme. Some notes if you're porting:

using System;
using System.Threading.Tasks;
using Statiq.App;
using Statiq.Web;

namespace ...
{
  public class Program
  {
    public static async Task<int> Main(string[] args) =>
      await Bootstrapper
        .Factory
        .CreateWeb(args)
        .RunAsync();
  }
}