LiVa: The "warning thingy"

Why LiVa Exists

While developing Alpha—originally just for myself—I kept running into small but annoying issues. I’d write a shortcode, come back to it days later, and forget which keys or values it accepted.

That frustration peaked when I spent hours debugging a major issue!

Why does the shortcode work on one page but not another?

The cause? A classic case of developer error: A typo.

Nothing unique about that frustration but that day it really stuck.
So I stopped everything and wrote a rudimentary block of code that would:

• Read shortcode inputs.
• Validate them against expected values.
• Throw a warnf message in Hugo’s terminal if there was a mismatch.
• Append a <div> on the page with the same message for visual feedback.

Simple, effective. Copy-pasted (DRY who?) into every shortcode. And done—so I thought.

From One-Time Shortcut to Persistent Helper

At this point, the theme was still personal. That changed when some non-tech friends grew skeptical after I told them:

“Anyone with an email address can have a personal website without spending a penny.”

They volunteered to try Alpha, and one of them actually loved that “warning thingy”.
Their excitement after their successful attempt was the catalyst: Alpha was going public.

Public Release Changed Everything

Going from private to public meant rewriting almost everything. Not for show, but because Alpha had to be as beginner-friendly as possible. Defaults and fallbacks everywhere.

The most time-consuming refactor was for that “warning thingy”, which now had to:

• Validate config files.
• Check page frontmatter.
• Inspect Markdown content.
• And of course, monitor shortcodes.

The plan was simple:

1. An error occurs.
2. A Go template detects and informs the JS counterpart.
3. A FAB (floating action button) on the page informs the user.
4. Clicking the FAB opens a modal with the error message and a suggested solution.

The modal would be hidden by default to avoid distracting from writing—aligning with Alpha’s core goals.

Unexpected User Behavior Issues

While my setup worked for me, I realized not everyone develops/writes like I do. Some users focus entirely on the editor without previewing pages in the browser.

Those users wouldn’t see LiVa’s FAB.

So LiVa needed terminal warnings too—even during builds. That way, if someone never previews their site but runs hugo to build, they’d still get feedback.

UI Struggles: Global vs. Local Scope

However a major issue remained, LiVa was not a fully global tool, and this is where things got tricky:

• User is viewing Page A.
• Editing Page B, where an error occurs (e.g. typo in SEO image filename).
• Hugo rebuilds Page B.
• Page A knows nothing of course, so no warning shown.
• User deploys with hidden errors.

Solutions I Explored:

1. Scanning public/: Not viable. It would require external dependencies, breaking Alpha’s “works out of the box” rule.

2. Using a global data store (.Store): This seemed perfect, but stored values persisted even after errors were fixed, forcing a server restart to clear them. I experimented with clearing the store dynamically, but the results were too unreliable, so I eventually dropped it.

That’s where I left it: LiVa isn’t globally scoped (yet), but it provides robust feedback within its current limits.

How LiVa Works Today

LiVa detects and reports ~40 errors

Terminal Warnings

• Global scoped.
• Guaranteed even during build.

LiVa Console

• Page-scoped errors show up only if that page is loaded in the browser.
• Global errors show on every page.

On-Page Alerts

• Errors affecting page flow (e.g. in shortcodes or Markdown) also appear inline, right where the issue occurs.

Extras

• Offline help for shortcodes, Markdown, LiVa itself.
• Checks for Alpha and Hugo updates.

Final Thoughts

Developing LiVa taught me more about Hugo than building the theme itself.

The self-imposed limitations (zero dependencies, no distractions) forced me to think more intuitively and balance my “developer ego” with real-world usability.

In the end LiVa evolved from a copy-pasted hack into a flexible framework controlled entirely through data files—making it expandable and potentially portable to other themes.

When I decided to make Alpha public, I didn’t expect that my most valuable contribution wouldn’t be just the theme’s design, but the tooling built into it. It’s what makes Alpha different from just another Hugo theme.

It’s a theme that actively helps you avoid mistakes.