A custom Hugo theme combining classic Macintosh typography with amber CRT terminal aesthetics. Features ASCII art, pixel-perfect rendering, and a blog-first design philosophy.

Created: December 2024
Hugo Version: 0.153.1+
Author: Kushagra Srivastava

1. Overview
2. Directory Structure
3. Installation
4. Configuration
5. Content Management
6. Customization Guide
7. Template Reference
8. CSS Architecture
9. ASCII Art & Visual Elements
10. Deployment
11. Troubleshooting
12. Future Enhancements

This theme merges two distinct aesthetics:

1. Classic Macintosh (System 7 era): Chicago font, clean typography, structured layouts, pixel-precise rendering
2. Amber CRT Terminal: Warm amber-on-black color scheme, scanline effects, blinking cursors, ASCII art decorations

The result is a nostalgic, readable blog theme that prioritizes content while maintaining strong visual identity.

• Amber monochrome color palette with glow effects
• CRT scanline overlay (subtle, non-intrusive)
• ASCII art header and footer decorations
• Date-first post listing (inspired by Chicago7 theme)
• Blinking cursor animations
• Chicago font with monospace fallbacks
• Fully responsive design
• No JavaScript dependencies (pure CSS)
• Clean, semantic HTML structure

your-hugo-site/
├── archetypes/
│   └── default.md
├── content/
│   ├── posts/
│   │   ├── my-first-post.md
│   │   └── another-post.md
│   └── about.md
├── layouts/
│   ├── _default/
│   │   ├── baseof.html      # Base template (wraps everything)
│   │   ├── single.html      # Individual post/page template
│   │   ├── list.html        # Section listing template
│   │   └── terms.html       # Taxonomy listing (tags, categories)
│   └── index.html           # Homepage template
├── static/
│   ├── css/
│   │   └── classic-mac.css  # Main stylesheet
│   └── fonts/
│       └── ChicagoFLF.ttf   # Chicago font file
├── hugo.toml                 # Site configuration
└── README.md                 # This file

• Hugo Extended v0.153.0 or later (extended version required for some CSS features)
• Git (for version control and deployment)
• A text editor (VS Code, Sublime, vim, etc.)

1. Create a new Hugo site:

   hugo new site my-blog
   cd my-blog

2. Create the directory structure:

   mkdir -p layouts/_default layouts/partials static/css static/fonts

3. Copy theme files:

   • Place baseof.html, single.html, list.html, terms.html in layouts/_default/
   • Place index.html in layouts/
   • Place classic-mac.css in static/css/

4. Download the Chicago font:

   • Search for "ChicagoFLF" font online
   • Place ChicagoFLF.ttf in static/fonts/
   • (Optional: the theme falls back to system monospace fonts if Chicago is unavailable)

5. Configure your site (see Configuration)

6. Run the development server:

   hugo server -D

1. Remove or comment out the theme setting in hugo.toml:

   # theme = "old-theme-name"

2. Copy the layout files to your project's layouts/ directory (not themes/)

3. Review your content front matter for compatibility (see Content Management)

4. Test locally before deploying

baseURL = "https://yourdomain.com/"
languageCode = "en-us"
title = "Your Site Title"

[params]
  description = "A brief description of your site"
  github = "yourusername"
  email = "[email protected]"

[menu]
  [[menu.main]]
    name = "Home"
    url = "/"
    weight = 1
  [[menu.main]]
    name = "Posts"
    url = "/posts/"
    weight = 2
  [[menu.main]]
    name = "About"
    url = "/about/"
    weight = 3

[markup]
  [markup.goldmark]
    [markup.goldmark.renderer]
      unsafe = true  # Allows raw HTML in markdown

[taxonomies]
  tag = "tags"
  category = "categories"

# Pagination
paginate = 10

# Summaries
summaryLength = 50

# Date format
[params]
  dateFormat = "January 2, 2006"

# Code highlighting (Hugo built-in)
[markup.highlight]
  style = "monokai"
  lineNos = false
  codeFences = true

hugo new posts/my-new-post.md

This creates a file at content/posts/my-new-post.md with default front matter.

---
title: "My Post Title"
date: 2024-12-22T10:30:00-05:00
draft: false
tags: ["hugo", "web", "tutorial"]
categories: ["tech"]
description: "A brief summary for SEO and previews"
---

content/
├── posts/           # Blog posts (date-ordered listing)
│   ├── 2024-01-15-first-post.md
│   └── 2024-02-20-second-post.md
├── projects/        # Project pages (optional section)
│   └── my-project.md
├── about.md         # Standalone page at /about/
└── _index.md        # Optional: customize section listing pages

Recommended: Prefix posts with dates for filesystem organization:

2024-12-22-my-post-title.md

The URL slug comes from the filename (minus date prefix if using permalinks config).

1. Option A: Static folder

   static/
   └── images/
       └── my-image.png
   

   Reference in markdown: ![Alt text](/images/my-image.png)

2. Option B: Page bundles (keeps images with content)

   content/
   └── posts/
       └── my-post/
           ├── index.md
           └── featured.png
   

   Reference in markdown: ![Alt text](featured.png)

• Standard markdown (headings, lists, links, images)
• Fenced code blocks with syntax highlighting
• Blockquotes
• Tables
• Raw HTML (if unsafe = true in config)
• Footnotes

Edit the CSS custom properties in static/css/classic-mac.css:

:root {
  --bg: #0a0a08;           /* Main background */
  --bg-light: #121210;     /* Slightly lighter bg (code blocks) */
  --amber: #ffb000;        /* Primary amber */
  --amber-dim: #cc8800;    /* Muted amber (dates, borders) */
  --amber-bright: #ffc832; /* Bright amber (titles, hover) */
  --amber-glow: rgba(255, 176, 0, 0.15); /* Glow effect */
  --text: #ffb000;         /* Main text color */
  --text-dim: #997a00;     /* Dimmed text */
  --link: #ffc832;         /* Link color */
}

Alternative Color Schemes:

Green Phosphor (P1):

:root {
  --amber: #33ff33;
  --amber-dim: #22aa22;
  --amber-bright: #66ff66;
  --amber-glow: rgba(51, 255, 51, 0.15);
  --text: #33ff33;
  --text-dim: #228822;
  --link: #66ff66;
}

Blue Terminal:

:root {
  --amber: #00aaff;
  --amber-dim: #0077aa;
  --amber-bright: #33ccff;
  --amber-glow: rgba(0, 170, 255, 0.15);
  --text: #00aaff;
  --text-dim: #005588;
  --link: #33ccff;
}

The theme uses Chicago font with fallbacks. To change:

1. Use a different font file:

   @font-face {
     font-family: 'YourFont';
     src: url('/fonts/YourFont.ttf') format('truetype');
   }
   
   body {
     font-family: 'YourFont', 'Monaco', 'Consolas', monospace;
   }

2. Use Google Fonts:

   @import url('https://fonts.googleapis.com/css2?family=VT323&display=swap');
   
   body {
     font-family: 'VT323', monospace;
   }

Recommended Retro Fonts:

• VT323 (Google Fonts) - classic terminal
• IBM Plex Mono (Google Fonts) - clean monospace
• Fira Code - programming font with ligatures
• JetBrains Mono - modern monospace

Edit layouts/index.html and find the <pre class="ascii-header"> block.

Generate ASCII art at:

• https://patorjk.com/software/taag/ (text to ASCII)
• https://www.asciiart.eu/ (pre-made art)
• https://asciiflow.com/ (draw your own)

Tips:

• Use fonts like "Standard", "Small", or "Banner" for readable results
• Test at different screen widths
• Escape any characters that conflict with HTML (<, >, &)

Edit layouts/_default/baseof.html and find the <pre class="ascii-footer"> block.

Current footer shows a small Mac icon. Replace with any ASCII art you prefer.

Remove or comment out this block in classic-mac.css:

/* CRT scanline effect */
body::before {
  /* ... */
}

body::before {
  background: repeating-linear-gradient(
    0deg,
    rgba(0, 0, 0, 0.05) 0px,  /* Lower = more subtle */
    rgba(0, 0, 0, 0.05) 1px,
    transparent 1px,
    transparent 2px
  );
}

Remove instances of <span class="cursor"></span> from templates, or hide via CSS:

.cursor {
  display: none;
}

Current style shows date on left, title on right. To flip:

.post-item {
  flex-direction: row-reverse;
}

.post-date {
  text-align: right;
}

For a simpler list without dates:

<ul class="post-list">
  {{ range .Pages }}
  <li class="post-item">
    <a href="{{ .Permalink }}" class="post-link">{{ .Title }}</a>
  </li>
  {{ end }}
</ul>

Hugo uses Go's html/template package. Key concepts:

baseof.html (base template)
    │
    ├── index.html (homepage, defines "main" block)
    ├── single.html (posts/pages, defines "main" block)
    ├── list.html (sections, defines "main" block)
    └── terms.html (taxonomies, defines "main" block)

baseof.html contains the shell (<html>, <head>, footer). Other templates fill in the {{ block "main" . }} section.

Site-wide (.Site):

• .Site.Title - Site title from config
• .Site.Params.description - Site description
• .Site.Params.github - GitHub username
• .Site.BaseURL - Base URL
• .Site.Menus.main - Main menu items
• .Site.RegularPages - All regular content pages

Page-specific (.):

• .Title - Page title
• .Content - Rendered markdown content
• .Date - Publication date
• .Permalink - Full URL to page
• .ReadingTime - Estimated reading time (minutes)
• .Params.tags - Tags array
• .PrevInSection - Previous page in section
• .NextInSection - Next page in section

Example: Custom template for projects section.

1. Create layouts/projects/single.html:

   {{ define "main" }}
   <article class="project">
     <h1>{{ .Title }}</h1>
     {{ with .Params.repo }}
     <a href="https://github.com/{{ . }}">View on GitHub</a>
     {{ end }}
     <div class="post-content">
       {{ .Content }}
     </div>
   </article>
   {{ end }}

2. Create content at content/projects/my-project.md:

   ---
   title: "My Project"
   repo: "username/repo"
   ---
   Project description here...

Partials are reusable template fragments. Create layouts/partials/:

<!-- layouts/partials/post-meta.html -->
<div class="post-meta">
  {{ .Date.Format "January 2, 2006" }}
  {{ with .Params.tags }} · {{ delimit . ", " }}{{ end }}
  · {{ .ReadingTime }} min read
</div>

Use in templates:

{{ partial "post-meta" . }}

The CSS is organized in sections:

1. Font imports and custom properties (:root)
2. Reset and base styles (*, html, body)
3. Layout components (.site-container, etc.)
4. Typography (headings, paragraphs, links)
5. Post listing styles (.post-list, .post-item)
6. Single post styles (.post-header, .post-content)
7. Interactive elements (buttons, navigation)
8. Decorative elements (ASCII, cursor, dividers)
9. Utility classes (.pixel-decoration, etc.)
10. Responsive styles (@media queries)

/* Mobile: 600px and below */
@media (max-width: 600px) {
  /* Adjustments for small screens */
}

Current responsive changes:

• Reduced padding on body
• Smaller ASCII art font size
• Post items stack vertically (date above title)

1. Add to appropriate section in CSS file
2. Use CSS custom properties for colors:

   .my-new-element {
     color: var(--amber);
     border-color: var(--amber-dim);
   }

3. Test on mobile using browser dev tools

Text Generators:

• TAAG - Text to ASCII Art
• ASCII Art Generator - Image to ASCII

Pre-made Art:

• ASCII Art Archive
• Christopher Johnson's ASCII Art

Drawing Tools:

• ASCIIFlow - Draw diagrams
• Monodraw - Mac app for ASCII art

For actual pixel art images (not ASCII):

1. Create or find a small pixel art image
2. Save as PNG with transparency if needed
3. Add to static/images/
4. Use in templates or markdown:

   <img src="/images/pixel-icon.png" class="pixel-decoration" alt="Icon">

The .pixel-decoration class ensures crisp rendering:

.pixel-decoration {
  image-rendering: pixelated;
  image-rendering: crisp-edges;
}

ASCII dividers you can use:

═══════════════════════════════════════
───────────────────────────────────────
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
┌─────────────────────────────────────┐
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓
╔═══════════════════════════════════════╗

1. Create .github/workflows/hugo.yml:

name: Deploy Hugo site to Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

defaults:
  run:
    shell: bash

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.153.1
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive
      - name: Install Hugo
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
          sudo dpkg -i ${{ runner.temp }}/hugo.deb
      - name: Build
        run: hugo --minify
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v4
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./public

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

2. Configure GitHub repository:

   • Go to Settings → Pages
   • Set Source to "GitHub Actions"

3. Set baseURL in hugo.toml:

   baseURL = "https://username.github.io/repo-name/"

4. Push to main branch - deployment happens automatically

1. Add CNAME file at static/CNAME:

   yourdomain.com
   

2. Configure DNS with your registrar:

   • For apex domain: A records pointing to GitHub's IPs
   • For subdomain: CNAME record to username.github.io

3. Update baseURL:

   baseURL = "https://yourdomain.com/"

Netlify:

1. Connect repository to Netlify
2. Build command: hugo --minify
3. Publish directory: public

Vercel:

1. Import repository to Vercel
2. Framework preset: Hugo
3. Build command: hugo --minify

Cloudflare Pages:

1. Connect repository
2. Build command: hugo --minify
3. Build output directory: public

"found no layout file" warnings:

• Ensure all template files are in correct locations
• Check for typos in filenames
• Verify theme is not set in config (or is commented out)

Styles not loading:

• Check CSS file path: should be static/css/classic-mac.css
• Verify the <link> tag path in baseof.html
• Clear browser cache (Ctrl+Shift+R)

Font not rendering:

• Verify font file is in static/fonts/
• Check @font-face path in CSS matches actual filename
• Font falls back to monospace if file is missing (this is fine)

ASCII art looks broken:

• Ensure white-space: pre is set
• Check for unescaped HTML characters (<, >, &)
• Reduce font size if wrapping occurs

Posts not showing:

• Check draft: false in front matter
• Verify posts are in content/posts/ directory
• Ensure date is not in the future

Changes not reflecting:

• Hugo server hot-reloads, but sometimes needs restart
• Run hugo server --disableFastRender for full rebuilds
• Delete public/ folder and rebuild: rm -rf public && hugo

Run Hugo with verbose output:

hugo server -D --verbose

Check what pages Hugo sees:

hugo list all

1. Right-click → Inspect to open DevTools
2. Elements tab: Check HTML structure
3. Console tab: Look for errors
4. Network tab: Verify CSS/fonts are loading
5. Responsive mode: Test different screen sizes

Ideas for extending this theme:

• Dark/light theme toggle
• Search functionality (using Pagefind or Fuse.js)
• Table of contents for long posts
• Reading progress indicator
• Comments (using Giscus or similar)
• RSS feed styling
• Syntax highlighting theme matching amber palette
• Image lightbox/zoom
• Related posts section
• Archive page by year/month

• More ASCII art decorations
• Animated ASCII art (CSS animations)
• Custom 404 page with ASCII art
• Loading screen effect
• "Boot sequence" animation on first visit
• Custom cursor
• Sound effects (optional, with toggle)

• Critical CSS inlining
• Font subsetting (reduce Chicago font size)
• Image optimization pipeline
• SEO meta tags partial
• Open Graph / Twitter cards
• JSON-LD structured data
• Accessibility audit and improvements
• Print stylesheet

# Start development server
hugo server -D

# Build for production
hugo --minify

# Create new post
hugo new posts/my-post.md

# Create new page
hugo new about.md

# List all content
hugo list all

# Check Hugo version
hugo version

• Hugo Documentation
• Hugo Discourse Forum
• Go Template Documentation
• CSS Custom Properties

This theme is provided as-is for personal use. Feel free to modify and adapt for your own projects.

Last updated: December 2025