Contributing to HugoBlox

April 2, 2026 · View on GitHub

HugoBlox exists to make academic publishing free, beautiful, and effortless — for every researcher on earth.

We power 100,000+ researcher websites, research lab sites, and university project pages worldwide. Behind each one is a scientist, student, or lab trying to share their work. Behind HugoBlox is a community of contributors who made that possible.

Note

Love HugoBlox? If it's helped you publish your research, launch your lab site, or build your academic presence — every contribution you make passes that forward to the next researcher who needs it. You're not just improving a tool. You're advancing open research.

Why Contribute?

🌍 Join the Movement

Advance open research — keep essential academic tools free and accessible worldwide
Shape what millions of researchers use — your changes land in sites across hundreds of universities
Be part of something bigger — HugoBlox is infrastructure for open science, not just a website builder

🎓 Grow Your Career

Add it to your CV — open source contributions signal collaboration, craft, and initiative
Build your public reputation — every contribution is permanently credited and visible
Level up with modern tech — Hugo, Tailwind CSS v4, Preact, Go, and more
Network globally — connect with researchers, developers, and academics worldwide

⚡ Quick Wins — Pick One!

Not every contribution requires code. Pick whatever fits your time:

Time	Action
30 sec	⭐ Star the repo — helps more researchers discover HugoBlox
30 sec	👍 Upvote a feature you need
5 min	🐛 Report a bug with clear steps to reproduce
5 min	💬 Answer a question in Discord
5 min	✏️ Fix a documentation typo — hit Edit on any docs page
1 hr	🔧 Pick a help wanted issue
few hrs	🧩 Contribute a significant feature or new block
ongoing	🎥 Create YouTube tutorials or blog posts

🛠️ Technical Setup

Important

All technical documentation — commands, architecture, code conventions, commit message standards, and how to build blocks — lives in AGENTS.md. That file is the single source of truth for both human contributors and AI agents working in this repo.

TL;DR:

# 1. Install: Hugo Extended, Node.js, pnpm
# 2. Clone and install deps
pnpm install

# 3. Start the dev server for a starter site
pnpm dev academic-cv      # opens at http://localhost:8081

See AGENTS.md for the full guide: architecture, all commands, code standards, commit conventions, block creation, and schemas.

🤝 Types of Contributions

Code & Blocks

Fix a bug — see open issues
Build a new block — see the block guide in AGENTS.md

Content & Community

Contribute a shortcode
Contribute a language pack — place in modules/blox/i18n/ and add metadata to modules/blox/data/languages.yaml
Contribute a theme pack — color and font themes
Contribute a template — duplicate the Link In Bio template as a starting point, then reach out on Discord

Note

To contribute to a template, make changes inside templates/ in this monorepo. Do not submit PRs to the dedicated template repositories — they are read-only and changes propagate there automatically.

Docs & Education

Improve the documentation — open a GitHub Issue with your suggested changes
Write tutorials or blog posts
Create YouTube walkthroughs

🔄 PR Process

Search first — check issues and PRs to avoid duplicate work
Open an issue first for significant new features — discuss design before building
Test locally — pnpm dev academic-cv before submitting
Run quality checks — pnpm code:fix && pnpm style:fix && pnpm format
Write a clear commit message — see commit conventions in AGENTS.md

Tip

For a simple bug fix or typo? Just open a PR directly — no issue needed.

💬 Getting Help

Discord #contributing — real-time help
GitHub Discussions — async Q&A and show-and-tell
GitHub Issues — bugs and feature requests

When reporting a bug, include: Hugo version, HugoBlox version (from go.mod), OS, and browser — plus the smallest example that reproduces it.

🏆 Recognition

Contributors are:

Named in release notes
Featured on our social media
Visible on the contributors page

💚 Can't Contribute Code?

Get Pro — enhance your productivity with automations whilst supporting HugoBlox
GitHub Sponsors — monthly support for open source development
☕ Buy a coffee
📢 Share your site on X/LinkedIn/Reddit with #HugoBlox

⚖️ Contributor License Agreement

By submitting a Pull Request, you agree to our CLA. In short: you keep ownership of your code; we get a permanent license to use it as part of HugoBlox. This is standard practice in professional open source and protects both you and the project.

Questions? Join our Discord or start a Discussion.

This project follows the Contributor Covenant Code of Conduct.