Projects Showcase

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):

[[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.

Projects and sections appear in the order listed, simply move blocks up or down to reorder.

Creating the Page

Create content/projects.md with the projects layout:

---
title: "Projects"
layout: "projects"
---

A collection of my work and side projects.

The layout: "projects" tells Hugo to use the projects template that reads from the data file. Any content we write below the front matter appears as an intro above the project cards.

Icons

For project icons, place SVG files in static/images/projects/ and reference them with absolute paths:

icon = "/images/projects/my-project.svg"

SVGs work best since they scale perfectly. Aim for simple, recognizable shapes, icons display at 50 by 50px.

Troubleshooting

Projects not appearing: Check that data/projects.toml exists with valid TOML syntax, the page has layout: "projects" in front matter, and restart Hugo server after changes.

Icons not loading: Paths must start with /, files must exist in static/images/, and extensions are case-sensitive.

TOML errors: Strings with special characters need quotes, use spaces (not tabs) for indentation, and check for missing brackets.