Posts on Mono

Getting Started with Mono

Sat, 25 Jan 2025 00:00:00 +0000

This guide walks through installing Mono and setting up a site.

Initial Setup

Install Hugo

Hugo is a fast static site generator. Follow the official Hugo installation guide. After installation, verify it works:

bash

hugo version

For full functionality, we recommend Hugo v0.139 or later as we tested Mono with this version.

Theme Configuration

Mon, 20 Jan 2025 00:00:00 +0000

This post covers all configuration options available in the Mono theme. For a getting started guide, see Getting Started with Mono.

Theme Configuration

Theme-wide settings are specified in hugo.toml. This file controls the overall behavior and appearance of Mono.

Site Parameters

The [params] section defines site metadata, features, and appearance:

toml
[params]
 author = "Your Name"
 description = "Site description for SEO"

 # Features
 showToC = true # Site-wide Table of Contents (override per-page)
 show_updated = true # Show visible "Updated" line when lastmod differs from date
 dateFormat = "Jan 2, 2006" # Go reference layout applied to post dates

 # Home page
 homePostCount = 3 # Number of recent posts on the home page
 homeProjectCount = 3 # Number of projects on the home page

 # SEO
 favicon = "images/favicon.svg"
 og_image = "images/og.png" # Default Open Graph image (override per-page)

 # Math (KaTeX only). Leave off to opt in per-page via `math: true` front matter.
 katex = false

 # Search
 enableSearch = true # Show header search icon and build /search/

 # Custom assets
 customCSS = ["css/custom.css"]
 customJS = ["js/custom.js"]

Parameter	Description
`author`	Displayed in footer and meta tags. Can be overridden per-page via front matter.
`description`	SEO meta description fallback when pages don’t specify one
`favicon`	Path relative to `static/` folder
`og_image`	Default social sharing image. Can be overridden per-page via front matter.
`homePostCount` / `homeProjectCount`	Number of items shown on the home page (default 3)
`customCSS`	CSS files in `assets/css/` (processed by Hugo)
`customJS`	JS files in `static/js/` (served as-is)

Language

Mono includes translations for UI elements in five languages. Set the default language at the top level of hugo.toml:

Deployment

Wed, 15 Jan 2025 00:00:00 +0000

Hugo generates a static site in public/ when you run hugo. This folder contains plain HTML, CSS, and JS that can be hosted anywhere. Below are step-by-step guides for three common platforms.

Netlify

Create netlify.toml in your site root:

toml
[build]
 command = "hugo --gc --minify"
 publish = "public"

[build.environment]
 HUGO_VERSION = "0.139.0"

[context.deploy-preview]
 command = "hugo --gc --minify --buildDrafts --baseURL $DEPLOY_PRIME_URL"

[context.deploy-preview.environment]
 HUGO_VERSION = "0.139.0"

Setup

Push your site to GitHub
Go to app.netlify.com > Add new site > Import an existing project
Select your repo. Netlify auto-detects the netlify.toml
Click Deploy site

The first build takes about 30 seconds. Netlify gives you a URL like https://random-name-12345.netlify.app.

Typography and Markdown

Fri, 10 Jan 2025 00:00:00 +0000

This guide covers all the basic Markdown formatting options available in the theme.

Basic Text Formatting

As is standard in Markdown, the basic formatting options are:

Bold text is created using double asterisks: **bold text**
Italic text is created using single asterisks: *italic text*
Inline code is created using backticks: `inline code`
~~Strikethrough~~: created using double tildes: ~~strikethrough~~
Links are created using: [Link Text](https://example.com)

Headings

Mono supports six levels of headings, each with appropriate sizing and spacing for clear visual hierarchy, which are created using hash symbols:

Images and Media

Sun, 05 Jan 2025 00:00:00 +0000

The Mono theme provides several options for incorporating images and media into posts with clean and responsive layouts.

Images

Image Placement

There are two main ways to organize images in a Hugo site:

1. Post Bundle (Recommended): Place images alongside the post in a folder, where the markdown file is named index.md and images are in the same directory:

content/posts/my-post/
├── index.md
├── image1.jpg
└── image2.png

Which is then referenced with:

Code Blocks

Mon, 30 Dec 2024 00:00:00 +0000

The Mono theme uses Chroma, Hugo’s built-in syntax highlighter, which supports hundreds of languages. The syntax color themes were generated using Hugo’s CLI:

bash
# Light theme (GitHub style)
hugo gen chromastyles --style=github > assets/css/syntax-light.css

# Dark theme (Catppuccin Mocha style)
hugo gen chromastyles --style=catppuccin-mocha > assets/css/syntax-dark.css

These are combined in assets/css/syntax.css and automatically switch based on the site’s light/dark mode.

Projects Showcase

Wed, 25 Dec 2024 00:00:00 +0000

Mono includes a projects showcase that displays work in an organized, card-based layout. Unlike blog posts, projects are defined in a single data file for easy management.

Setting Up Projects

Create data/projects.toml to define projects. The file organizes projects into sections (categories) containing items (individual projects):

toml
[[section]]
 name = "Open Source"
 description = "Projects I maintain and contribute to"

 [[section.items]]
 title = "My App"
 description = "A useful application"
 url = "https://github.com/username/my-app"
 icon = "/images/projects/my-app.svg"

 [[section.items]]
 title = "CLI Tool"
 description = "A command-line utility"
 url = "https://github.com/username/cli-tool"
 symbol = "CLI"

[[section]]
 name = "Client Work"
 description = "Selected professional projects"

 [[section.items]]
 title = "Portfolio Site"
 description = "Personal website built with Hugo"
 url = "https://example.com"
 symbol = "WEB"

Each section has a name (required) and optional description. Each item requires title, description, and url. For the visual identifier, provide either an icon (path to an image, ideally SVG) or a symbol (2-3 character text fallback). If neither is specified, “PRJ” is used as the default.