Marcus Hugo Theme

A minimal Hugo theme for personal blogs with two content types: Posts (long-form) and Micro (short-form). Features clean design, dark mode, and org-mode support.

Features

• Minimal Design - Clean typography and uncluttered layouts
• Dark Mode - Manual toggle with localStorage persistence (defaults to light)
• Two Content Types - Posts (long-form) and Micro (short-form) content
• Responsive Design - Mobile-first approach
• Table of Contents - Right-side TOC for posts (desktop only)
• Configurable Navigation - Hugo menu system
• Social Sharing - Open Graph meta tags
• Favicon Support - Modern favicon implementation
• Org-mode Ready - Full support for org-mode syntax

Quick Start

Installation

# Add as git submodule
cd your-hugo-site
git submodule add https://github.com/yourusername/marcus-hugo.git themes/marcus-hugo

# Or download and extract to themes/marcus-hugo

Basic Configuration

Add to your hugo.toml:

baseURL = 'https://yoursite.com'
languageCode = 'en-us'
title = 'Your Site Title'
theme = 'marcus-hugo'

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = false  # Secure by default
  [markup.highlight]
    style = 'github'
    lineNos = false
  [markup.tableOfContents]
    startLevel = 1
    endLevel = 6

[params]
  author = 'Your Name'
  description = 'Your site description'

# Navigation menu
[menu]
  [[menu.main]]
    name = "Home"
    url = "/"
    weight = 10
  [[menu.main]]
    name = "Posts"
    url = "/posts/"
    weight = 20
  [[menu.main]]
    name = "Micro"
    url = "/micro/"
    weight = 30

Required Files

Place in your static/ directory:

• favicon.ico (32x32 px)
• icon.svg (scalable vector)

Content Types

Posts (/content/posts/)

Long-form articles with TOC navigation:

---
title: "Your Post Title"
date: 2024-01-15T10:00:00Z
tags: ["tag1", "tag2"]
image: "/images/post-image.jpg"  # Optional for social sharing
---

Micro (/content/micro/)

Short thoughts, quotes, and quick notes:

---
title: "Optional Title"  # Can be empty
date: 2024-01-15T10:00:00Z
tags: ["tip", "quick"]
---

Build Commands

# Development
hugo server -s exampleSite --themesDir=.. --theme=.

# Production build
hugo -s exampleSite --themesDir=.. --theme=.

# Build from anywhere
hugo -s /path/to/exampleSite --themesDir=.. --theme=.

Customization

Navigation

Modify the menu.main section in hugo.toml to add/remove menu items.

Colors

Edit CSS custom properties in assets/css/main.css:

:root {
  --bg-color: #ffffff;
  --text-color: #24292f;
  --code-bg: #f3f4f6;
  --link-color: #0969da;
}

Override Templates

Create files in your site’s layouts/ directory to override theme templates.

License

MIT License - see LICENSE file.

Pending Features

• [X] Fix image display in list views - Added replaceRE to fix relative image paths in micro list template
• [ ] Fix CSS specificity issues - remove !important overrides
• [ ] Add Twitter Cards meta tags
• [ ] Make micro cards clickable to open as separate page
• [ ] Fix TOC links to change color when scrolling to sections
• [ ] Fix dark mode code snippet colors for better visibility

Support

Check exampleSite/ for usage examples or open a GitHub issue.