hugOS - Hugo Theme by Paradox

Getting Started

Wed, 10 Jan 2024 00:00:00 +0000

Getting Started

hugOS turns a Hugo site into a small “web desktop”. Every section of your content becomes an app; individual pages, images and links open in draggable, resizable windows. There is no build step beyond Hugo and no JavaScript framework - the whole desktop is plain HTML, CSS and one vanilla JS file.

This Handbook is itself an example: it is the docs/ content section rendered as a wiki app. Everything you are reading lives in content/docs/*.md.

Installation & Setup

Thu, 11 Jan 2024 00:00:00 +0000

Installation & Setup

hugOS is a standard Hugo theme. Hugo Extended (v0.146.0 or newer) is recommended. It is strictly required only if your photo galleries contain raster images (JPG/PNG) - those get converted to WebP thumbnails, and WebP encoding needs Extended. SVG-only galleries and everything else run on standard Hugo just fine. (Check your build with hugo version; Extended shows +extended in the string.)

1. Add the theme

Pick whichever method matches how you manage your site.

Configuring the Desktop

Fri, 12 Jan 2024 00:00:00 +0000

Configuring the Desktop

Everything on the desktop is declared in data/desktop.yaml. There are three top-level keys: profile, bookmarks and apps.

`profile`

Identity shown in the launcher header, the About/terminal whoami, and meta tags.

profile:
 name: "Paradox"
 role: "Fullstack Developer"
 initials: "P" # shown in the launcher avatar
 email: "paradox@example.com"
 about: "One-line bio for the launcher and terminal."

`bookmarks`

Tiles shown on the browser app’s home page.

bookmarks:
 - { label: "GitHub", icon: "🐙", url: "https://github.com/octocat" }
 - { label: "Hugo", icon: "📘", url: "https://gohugo.io" }

`apps`

A list. Each entry becomes a desktop icon, a launcher entry, and a window. Order in the list is the order of the icons.

App Types Reference

Sat, 13 Jan 2024 00:00:00 +0000

App Types Reference

The type field on each app decides what it does. Types fall into two groups: those that open your content, and built-in tools that need no content.

Content apps

`type`	Opens	Requires
`page`	a single markdown page as a document	`source: "<page>"`
`folder`	a content section as a file manager	`source: "<section>"`
`wiki`	a content section as a sidebar wiki	`source: "<section>"`
`gallery`	an image page-bundle as a photo gallery	`source: "<bundle>"`

`page`

Opens one markdown file in a document window.

Adding Content

Sun, 14 Jan 2024 00:00:00 +0000

Adding Content

Content lives in content/, exactly as in any Hugo site. The desktop file decides which content shows up as which app; this page covers how to write the content itself.

A single page

Create a markdown file and point a page app at it.

<!-- content/about.md -->
---
title: "About Me"
---

# Hi, I'm Paradox

Your content here…

# data/desktop.yaml
- { id: about, label: "About Me", icon: "📄",
 title: "About Me - Notes", type: page, source: "about" }

The document window renders whatever the markdown produces, so the leading # Heading is your page title.

Photo Galleries

Mon, 15 Jan 2024 00:00:00 +0000

Photo Galleries

A gallery app renders an image page-bundle as a thumbnail grid with a lightbox.

Folder layout

A page bundle is a folder with an index.md and the images beside it:

content/photos/
├── index.md
├── 01-aurora.jpg
├── 02-dunes.jpg
└── 03-forest.svg

<!-- content/photos/index.md -->
---
title: "Photos"
---

# data/desktop.yaml
- { id: photos, label: "Photos", icon: "🖼️",
 title: "Photos - Gallery", type: gallery, source: "photos" }

How images are handled

Raster images (JPG, PNG, WebP) are resized to fit a 600×600 box and encoded as WebP thumbnails, loaded lazily. The lightbox shows the full original. (WebP encoding needs Hugo Extended - see Installation & Setup.)
SVGs are used as-is for both thumbnail and full view.

Captions

Captions are derived automatically from the file name: numeric prefixes and separators are stripped and the rest is title-cased. So 01-blue_hour.jpg becomes “Blue Hour”. Name your files descriptively and you get captions for free.

Customization & Settings

Tue, 16 Jan 2024 00:00:00 +0000

Customization & Settings

There are two layers of customization: defaults you set in config, and choices visitors make in the Settings app (saved in their browser).

Defaults in config

# hugo.toml
[params]
 accent = "#3daee9" # desktop accent colour

The accent colour drives highlights, focus rings, the launcher hover, and links. Pick something that reads well on both the dark and light themes.

The Settings app

Add a settings app and visitors get a live control panel:

SEO & No-JS Pages

Wed, 17 Jan 2024 00:00:00 +0000

SEO & No-JS Pages

The desktop is a single page powered by JavaScript - but the content is not trapped inside it. Every piece of content also exists as a plain, crawlable Hugo page.

Why this matters

Search engines index the real pages, not a blank <div>.
No-JS visitors (and tools, readers, archivers) still get the content.
Deep links to /blog/some-post/ work and render a readable page.

How it works

Alongside the desktop, the theme renders the normal Hugo page tree:

Easter Eggs

Thu, 18 Jan 2024 00:00:00 +0000

Easter Eggs

hugOS hides a few things for the curious. None of them affect your content or the plain, indexable pages - they are pure decoration. Here is the full list, so nothing stays a secret if you don’t want it to.

Time travel

Click the clock in the panel, then the 🕰 button in the calendar (or use the desktop’s context menu). Pick a year and the whole desktop re-skins itself:

Markdown Showcase

Mon, 15 Jan 2024 00:00:00 +0000

Markdown showcase

A quick taste of how rich content renders inside a document window.

Text

You get bold, italic, ~~strikethrough~~, and inline code. Links look like this.

A list

First
Second
- nested
- items
Third

A quote

Simplicity is the ultimate sophistication.

Code

function greet(name) {
 return `Hello, ${name}!`;
}

A table

Feature	Status
Windows	✅
Terminal	✅
Browser	✅

Ut enim ad minim veniam

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

Itaque earum rerum hic tenetur a sapiente delectus, ut aut reiciendis voluptatibus maiores alias consequatur aut perferendis doloribus asperiores repellat.

Nam libero tempore, cum soluta nobis est eligendi optio cumque nihil impedit quo minus id quod maxime placeat facere possimus, omnis voluptas assumenda est, omnis dolor repellendus.

Temporibus autem quibusdam et aut officiis debitis.
Aut rerum necessitatibus saepe eveniet ut et voluptates.
Repudiandae sint et molestiae non recusandae.

On a longer note, lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Sed do eiusmod tempor

Thu, 12 Sep 2024 00:00:00 +0000

At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium voluptatum deleniti atque corrupti quos dolores et quas molestias excepturi sint occaecati cupiditate non provident.

Et harum quidem rerum facilis est et expedita distinctio. Nam libero tempore, cum soluta nobis est eligendi optio cumque nihil impedit quo minus id quod maxime placeat facere possimus.

lorem ipsum dolor sit amet
consectetur adipiscing elit

Temporibus autem quibusdam et aut officiis debitis aut rerum necessitatibus saepe eveniet ut et voluptates repudiandae sint et molestiae non recusandae.

Consectetur adipiscing elit

Sat, 18 May 2024 00:00:00 +0000

Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo.

A few placeholder points:

Nemo enim ipsam voluptatem quia voluptas sit aspernatur.
Neque porro quisquam est qui dolorem ipsum quia dolor sit amet.
Ut enim ad minima veniam, quis nostrum exercitationem ullam.

Quis autem vel eum iure reprehenderit qui in ea voluptate velit esse quam nihil molestiae consequatur, vel illum qui dolorem eum fugiat quo voluptas nulla pariatur.

Lorem ipsum dolor sit amet

Fri, 02 Feb 2024 00:00:00 +0000

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit.

About Me

Mon, 01 Jan 0001 00:00:00 +0000

Paradox

Fullstack Developer - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Curriculum Vitae

Mon, 01 Jan 0001 00:00:00 +0000

Paradox

Fullstack Developer · Lorem City paradox@example.com · example.com · github.com/paradox-ng

Summary

Experience

Senior Fullstack Developer - Dolor Studio

2021 - Present · Remote

Lorem ipsum dolor sit amet, consectetur adipiscing elit.
Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.
Duis aute irure dolor in reprehenderit in voluptate velit esse.

Fullstack Developer - Eiusmod Labs

2017 - 2021 · Tempor

Photos

Mon, 01 Jan 0001 00:00:00 +0000