DEV Community: Oxypteros

We're All Temporarily Abled

Oxypteros — Fri, 24 Oct 2025 17:11:39 +0000

We like to separate things into neat boxes:

Accessibility for disabilities,
Usability for convenience,
Performance for speed.

But the ultimate question for a project should be: Can a human reach, read, and use what we built?

The box-model, while it is the foundation of the web, as a thought model is faulty.

A dark-only theme that becomes unreadable in daylight is just a “usability issue”?
A bloated page that never loads on a weak connection is just a “performance issue”?
A flashing animation that distracts people is just a “usability issue”?

All of them disable access and therefore, all of them are accessibility issues?
It doesn't matter what box you pick because the box doesn't exist.

We’re All Temporarily Abled

Most people think of web accessibility under the prism of "helping people with disabilities". This creates a soft boundary of them/us. But "true accessibility" is about everyone!

It's Inclusivity!

Because, in reality, we are all abled only for a timeframe.

Can a user with tired eyes, a dim phone screen or just under direct sunlight can access a well-build site better than one with a screen reader?

You have 20/20 eyesight and can read the stylish tiny text but tomorrow?

You have a fast laptop now, but next month you’ll be stuck with poor signal on a slow device trying to open a 10MB web page.

In all those moments, you are temporarily disabled, not by your body, but by design choices that didn’t consider your situation.

Inclusivity isn’t only about a fixed group of users with disabilities. It’s about developing and designing for variability. For human conditions that shift with age, environment, attention, or technology.

The modern developer should have a unique mantra:
“No matter who you are, where you are, or how you access it, you can use it.”

The Broader Responsibility

If a website is not screen reader friendly, too heavy for slow networks, too dark for daylight, too flashy for concentration, or too rigid for older devices, it’s not inclusive.

It’s tunnel-vision design. Assuming the world will always meet the developer’s setup.

Inclusivity is humble. It recognizes that everyone becomes disabled, even if only for a moment.

So when we design for inclusivity we’re not checking a box.
We’re simply future-proofing our humanity—making sure that when it’s our turn to be the one “disabled to access,” we’ll still be able to see, read, and connect.

“Develop like everyone’s ability expires tomorrow, because in some way, it does.”

Installing Hugo on Linux: The Reliable Way

Oxypteros — Fri, 18 Jul 2025 12:19:15 +0000

Recently, a user trying to get started with my theme, got stuck. They had tried to install Hugo on Ubuntu, followed a few different guides, and ended up with multiple, conflicting Hugo versions on their system. Their frustration was palpable, and it's a story I've come across more than once.

The official Hugo docs are great, but the Linux ecosystem has a few quirks. This guide is my attempt to provide a crystal-clear, "do this and it will work" method for Linux users.

Three Rules

Before we touch the terminal, let's establish three rules. Following these will save you from 99% of future problems.

Avoid Your Distro's Package Manager. This is the most important rule (apt, dnf, etc) almost always contain outdated versions of Hugo. In some cases two years old.
Check Your Theme's Requirements. Themes require a minimum Hugo version to work. Always check the theme's theme.toml file first.
Update How You Installed. If you install manually, you must update manually. If you used a snap package, stick with that. Mixing installation methods is the fastest way to break your setup.

With that said, let's install Hugo.

My recommendation: Manual Installation

The safest, most reliable, problem-free method is to install the pre-compiled binary from Hugo's official GitHub releases. It has never failed me.
This is my preferred method for all my Linux machines. It's clean, simple, and gives you full control.

Step 1: Download the Correct Archive

Go to the Hugo Releases page. Expand the Assets list, for the version you need and find the extended version for your system.
For most users this will be: hugo_extended_[VERSION]_linux-amd64.tar.gz

Step 2: Download it

Make sure is saved to your ~/Downloads folder.

Debian/Ubuntu and derivatives:
You can download the .deb file from the Assets list and install it with: sudo dpkg -i hugo_extended_*_linux-*.deb

This works well, but the manual method below works on any Linux distribution.

Step 3: Install Hugo with a single Copy/Paste

This command block will create the necessary directory, extract the hugo binary into it, and make it executable.
It's the simplest way to perform a local install.

Open a terminal and run this command block:

(
  set -e
  mkdir -p ~/.local/bin
  tar -xvzf ~/Downloads/hugo_extended_*.tar.gz -C ~/.local/bin/ hugo
  hugo version
)

Note: This command assumes you only have one Hugo tar.gz file in your Downloads/ folder. If it fails, make sure that's the case.

Step 4: Add Hugo to your PATH (One-Time Setup)

The final step is to make sure your system knows where to find the hugo command. You may need to add ~/.local/bin to your system's PATH.

Restart your terminal and run hugo version.
If it works: You're done! Your PATH is already configured correctly.

If it says "command not found": You need to edit your shell's startup file.

Run the following command:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

Then, restart your terminal or run source ~/.bashrc. (If you use Zsh, change .bashrc to .zshrc).

How to Update Hugo Manually

Updating is now simple. Just repeat the process:

Download the new version from GitHub.
Run the same single command block from Step 3. It will overwrite the old hugo binary with the new one.

The hugo-install Script

For my own use, I wrapped this entire process into a small Bash script.

It does the same thing as the commands above, but it's a bit smarter. It checks for errors and also gives you the option to install Hugo globally for all users.

The Fast One-Liner

This is the fastest way. This command downloads the script, names it hugo-install, and makes it executable, all in one go.

curl -s -o hugo-install https://alpha.oxypteros.com/downloads/hugo-install && chmod +x hugo-install && echo "Script 'hugo-install' downloaded to: $(pwd)/hugo-install"

After downloading, you can inspect the script with cat hugo-install or open it in a text editor to see exactly what it does before running it with ./hugo-install.

The Manual Way

If you prefer, you can create the file yourself. Save the code below as hugo-install, make it executable with chmod +x hugo-install, and run it.

#!/bin/bash
# A script to safely install the latest version of Hugo on Linux.
# It's designed to be run after downloading the .tar.gz file from GitHub.

# Exit immediately if a command exits with a non-zero status.
set -e

# Configuration & Colors
GREEN='\e[32m'
RED='\e[31m'
YELLOW='\e[33m'
BOLD_GREEN='\e[1;32m'
RESET='\e[0m'

# Path Variables
DOWNLOADS_DIR="$HOME/Downloads"
LOCAL_INSTALL_DIR="$HOME/.local/bin"
GLOBAL_INSTALL_DIR="/opt/hugo"
GLOBAL_SYMLINK_PATH="/usr/local/bin/hugo"

# Main Script
echo -e "${BOLD_GREEN}Starting Hugo Installer...${RESET}"

# Find the Hugo archive.
echo "Searching for 'hugo_*_linux-*.tar.gz' in '$DOWNLOADS_DIR'..."
HUGO_ARCHIVES=$(find "$DOWNLOADS_DIR" -maxdepth 1 -name "hugo_*_linux-*.tar.gz")
ARCHIVE_COUNT=$(echo "$HUGO_ARCHIVES" | grep -c .)

# Handle cases with zero or multiple archives found.
if [ "$ARCHIVE_COUNT" -eq 0 ]; then
  echo -e "${RED}Error: No Hugo archive found.${RESET}"
  echo "Please download the 'hugo_*_linux-*.tar.gz' file from GitHub Releases and place it in your '$DOWNLOADS_DIR' folder."
  echo "URL: https://github.com/gohugoio/hugo/releases"
  exit 1
elif [ "$ARCHIVE_COUNT" -gt 1 ]; then
  echo -e "${RED}Error: Multiple Hugo archives found.${RESET}"
  echo "Ensure there is only ONE 'hugo_*_linux-*.tar.gz' file in your '$DOWNLOADS_DIR' folder and run this script again."
  echo -e "Found files:\n$HUGO_ARCHIVES"
  exit 1
fi

echo -e "${GREEN}Found Hugo archive: $(basename "$HUGO_ARCHIVES")${RESET}"

# Ask the user for installation type.
read -p "Install Hugo for the current user only (local)? [Y/n] " -n 1 -r
echo 

if [[ $REPLY =~ ^[Nn]$ ]]; then
  # Global Installation
  echo -e "\n${BOLD_GREEN}Starting global installation...${RESET}"
  echo "Hugo will be installed in '$GLOBAL_INSTALL_DIR' and symlinked to '$GLOBAL_SYMLINK_PATH'."

  # Create destination directory if it doesn't exist.
  if [ ! -d "$GLOBAL_INSTALL_DIR" ]; then
    echo "Creating destination directory (requires sudo)..."
    sudo mkdir -p "$GLOBAL_INSTALL_DIR"
  fi

  # Extract directly into the destination directory.
  echo "Extracting 'hugo' binary to '$GLOBAL_INSTALL_DIR' (requires sudo)..."
  sudo tar --no-same-owner -xvzf "$HUGO_ARCHIVES" -C "$GLOBAL_INSTALL_DIR" hugo
  sudo chmod +x "$GLOBAL_INSTALL_DIR/hugo" 

  # Check and create symlink.
  if [ -L "$GLOBAL_SYMLINK_PATH" ]; then
    if [ "$(readlink "$GLOBAL_SYMLINK_PATH")" != "$GLOBAL_INSTALL_DIR/hugo" ]; then
        echo -e "${YELLOW}Warning: Existing symlink at '$GLOBAL_SYMLINK_PATH' points to a different Hugo installation.${RESET}"
        echo "You may need to remove it manually if you want to use this new version."
    else
        echo -e "${GREEN}Symlink already correctly points to the new installation.${RESET}"
    fi
  else
    echo "Creating symlink in /usr/local/bin (requires sudo)..."
    sudo ln -s "$GLOBAL_INSTALL_DIR/hugo" "$GLOBAL_SYMLINK_PATH"
  fi

else
  # Local Installation
  echo -e "\n${BOLD_GREEN}Starting local installation...${RESET}"
  echo "Hugo will be installed in '$LOCAL_INSTALL_DIR'."

  # Create destination directory if it doesn't exist.
  if [ ! -d "$LOCAL_INSTALL_DIR" ]; then
    echo "Creating destination directory: $LOCAL_INSTALL_DIR"
    mkdir -p "$LOCAL_INSTALL_DIR"
  fi

  # Extract directly into the destination directory.
  echo "Extracting 'hugo' binary to '$LOCAL_INSTALL_DIR'..."
  tar --no-same-owner -xvzf "$HUGO_ARCHIVES" -C "$LOCAL_INSTALL_DIR" hugo
  chmod +x "$LOCAL_INSTALL_DIR/hugo"

  # Check if the install directory is in the user's PATH and provide instructions if not.
  if [[ ":$PATH:" != *":$LOCAL_INSTALL_DIR:"* ]]; then
    echo -e "\n${YELLOW}IMPORTANT POST-INSTALL ACTION${RESET}"
    echo "To use hugo from your terminal, you need to add '$LOCAL_INSTALL_DIR' to your PATH."
    echo "Run the following command, then restart your terminal:"
    echo -e "${BOLD_GREEN}echo 'export PATH=\"\$HOME/.local/bin:\$PATH\"' >> ~/.bashrc${RESET}"
    echo "(If you use Zsh, change '.bashrc' to '.zshrc')"
  fi
fi

# Final Verification
echo -e "\n${BOLD_GREEN}Installation complete!${RESET}"
echo "Verifying Hugo version:"
# Use the full path to ensure we're running the one we just installed.
if [[ $REPLY =~ ^[Nn]$ ]]; then
    "$GLOBAL_SYMLINK_PATH" version
else
    "$LOCAL_INSTALL_DIR/hugo" version
fi

That's it. Whether you do it manually or with the script, you now have a rock-solid Hugo installation that will serve you well.

The Accidental Framework: How a Simple Warning Became a Hugo Validation Tool

Oxypteros — Wed, 16 Jul 2025 15:31:44 +0000

TL;DR

I built LiVa, a small validation framework for my Hugo theme, Alpha, to catch common errors in config files, frontmatter, and shortcodes before they go live. This is the story of how a simple hack evolved into a core feature.

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:

An error occurs.
Go templates detects and informs the JS counterpart.
A FAB (floating action button) on the page informs the user.
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 deploy, 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:

Scanning public/ : Not viable. It would require external dependencies, breaking Alpha’s “works out of the box” rule.
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.

If you're interested in the theme or the code behind LiVa, you can explore them on GitHub. Feedback or questions are always welcome!