Welcome, researchers and academics! Whether you're a professor sharing your publications, a PhD student building your first portfolio, or an AI researcher showcasing your work โ this guide will help you contribute to the tool that powers 100,000s of researcher and lab websites worldwide.
If Hugo Blox has saved you hours, taught you something, or helped you share your work, please take 2 minutes to give back. Most people won't โ but if a small part of the community pitches in today, we can ship faster, fix more bugs, and keep the project healthy for everyone.
We want contributing to Hugo Blox to be fun, enjoyable, and educational for anyone and everyone. All contributions are welcome, including new plugins (such as new widgets, shortcodes, theme packs, and language packs), templates, features, documentation as well as updates and tweaks, blog posts, YouTube tutorials, live streaming customizations, meetups, and more.
- ๐ Add to your CV: Open source contributions demonstrate technical skills and collaboration
- ๐ Build your reputation: Your contributions are publicly visible and credited
- ๐ค Network with peers: Connect with researchers and developers worldwide
- ๐ Learn modern web tech: Gain experience with Hugo, Tailwind CSS, and modern web development
- ๐ฌ Shape the tool you use: Directly influence features that matter to academics
- โก Get fixes faster: Contributing means your needs get addressed sooner
- ๐ฑ Support open research: Keep academic tools free and accessible to all
- ๐ Join 9k+ stars: Be part of a thriving academic community
- โญ Star the repository: github.com/HugoBlox/kit
- ๐ Vote on issues: Shape the roadmap by upvoting features you need
- ๐ก Suggest an enhancement: Have an idea? Create a GitHub Issue for the community to vote on
- ๐ข Share your site: Post your Hugo Blox site on X/LinkedIn/Reddit with #HugoBlox
- ๐ธ Share a screenshot: Show your beautiful site in Discussions
- ๐ Report issues clearly: Found a bug? Help us fix it with clear steps to reproduce
- ๐ฌ Help in Discord: Answer a question in our Discord community
- โ๏ธ Fix documentation typos: Spot an error? Fix it directly on GitHub (no setup needed!)
- ๐ง Implement a small issue: See help-wanted issues
- ๐ Write documentation: Help keep the documentation complete and up-to-date
- ๐งฉ Take a larger issue: Contribute a significant feature or improvement
- ๐ฅ Create tutorials: Record a YouTube video or write a detailed blog post
Join the Contributing channel on the community Discord.
Whether or not you're a developer, there are plenty of non-technical ways that you can help. We always need help with:
- Helping the Hugo Blox community via the live chat and forum
- Investigating and reviewing open Issues and Pull Requests
- Influence the roadmap! Give a thumbs up ๐ to upvote a feature request you would like to use
- Improving the documentation and writing tutorials
- Just click the Edit button at the bottom of pages or open an issue with your proposed improvement
- Testing and quality assurance, such as checking the latest version of the templates work as you expect and fixing any dead-links etc.
- Translating the Hugo Blox templates or the Hugo Blox documentation
- Hosting local Hugo Blox themed events or meetups
- Promoting Hugo Blox to others by blogging, vlogging, code streaming, talking etc.
No Go experience needed! Most contributions only require basic HTML/CSS knowledge.
-
Install Node.js (for Tailwind CSS v4)
# macOS/Linux (using Homebrew) brew install node # Windows (download from nodejs.org) # Or use WSL2 for a Linux environment
-
Install pnpm (our package manager)
npm install -g pnpm
-
Install Hugo Extended (latest version)
# macOS brew install hugo # Windows (using Chocolatey) choco install hugo-extended # Linux snap install hugo --channel=extended
-
Fork & Clone
# Fork on GitHub first, then: git clone https://github.com/YOUR-USERNAME/kit.git cd kit
-
Install Dependencies
pnpm install
-
View a Starter Site
# View the academic-cv starter (most popular) ./scripts/view-starter-dev.sh academic-cv # Site opens at http://localhost:8081
That's it! You're ready to contribute. ๐
kit/
โโโ modules/
โ โโโ blox/ # Main theme module
โ โโโ layouts/ # HTML templates (easy to edit!)
โ โโโ assets/css/ # Tailwind CSS v4 styles
โ โโโ i18n/ # Translations (help translate!)
โโโ templates/
โ โโโ academic-cv/ # CV/Resume template
โ โโโ blog/ # Blog template
โ โโโ documentation/ # Docs template
โโโ scripts/ # Helper scripts
Note: To contribute an improvement to a template, make your changes to the relevant template within the templates/ folder. Do not submit PRs to the dedicated template repositories as they are read-only (changes are automatically propagated there from this mono-repository).
If you're a developer looking to contribute, but you're not sure where to begin, check out the help wanted label on Github, which contains issues which need some love.
If you have a straightforward bug fix or improvement, feel free to contribute it in a Pull Request for the community to review.
If you have an idea for a new feature, please start by searching the issues to check that the feature has not already been suggested and then suggest it by opening a new issue, as adding new features to Hugo Blox first requires some analysis around the design and spec.
Please be mindful of the project scope.
Create and publish your own blox
Create and publish your own shortcode
To contribute a new language pack or an improvement to a language pack, refer to the language pack guide. Once created, fork HugoBlox Kit, place your language pack in modules/blox/i18n/, add the language metadata to modules/blox/data/languages.yaml, and open a Pull Request on Github with these two files.
View the guide to contributing a color and font theme pack.
Consider duplicating a bare-bones template, such as the Link In Bio folder, and building up your own template using the Hugo Blox. Reach out on the Contributing channel in Discord to submit your template.
To contribute to Hugo Academic CLI, the automatic publication and blog post importer, refer to its dedicated Github repository and Issue queue.
- ๐ฃ๏ธ Discord: Real-time chat in #contributing channel
- ๐ฌ Discussions: Async help in GitHub Discussions
- ๐ Issues: Bug reports and feature requests
- Share your environment: Hugo version, HugoBlox version in
go.mod, OS, browser - Provide minimal reproduction: Smallest example showing the issue
- Check existing issues: Your question might be answered
- Be specific: "Publications not showing" โ "BibTeX import fails with DOI links"
- ๐๏ธ Credits: Named in release notes
- ๐ท๏ธ Contributor badge: On your GitHub profile
- ๐ฃ Social shoutouts: Featured on our social media
- ๐ฏ Direct impact: Your needs prioritized
- ๐ค Network access: Connect with core team
Check our Contributors page to see everyone who's helped!
- ๐ฐ Sponsor:
- All Access - One-time payment for exclusive Pro templates and blocks
- GitHub Sponsors - Monthly donation to support open source development
- โ๏ธ Donate a coffee
- ๐ข Spread the Word: Share your Hugo Blox site and experience
- ๐ Write Tutorials: Blog about your Hugo Blox setup
- ๐ฅ Create Videos: YouTube tutorials help many researchers
- ๐ Translate: Help make Hugo Blox accessible globally
To create a consistent experience for all contributors and help prevent bugs, we have some best practices.
Please follow the Conventional Commits Specification.
For example:
- new feature:
feat: add the X parameter - bug fix:
fix: typo in implementation of X parameter - performance:
perf: speed up init by pre-warming only pages - refactor:
refactor: simplify citation logic - docs:
docs: document the X parameter - style:
style: change font color from black to blue - build-related:
chore: rebuild JS assets
pnpm install
pnpm run lint
pnpm run formatPlease be mindful that although we encourage feature requests, we cannot expand the scope of the project in every possible direction. There will be feature requests that don't make the roadmap.
Every feature requires effort not just to analyse the requirements, design it, implement it, test it, document it, merge it, write release notes for it, and release it, but also to continuously support users with it and maintain it (fixing and refactoring the feature as the project and its dependencies evolve).
The more regular active volunteers (rather than one-off contributors) we have supporting users and maintaining the project, the more feasible it becomes to expand the scope of the project.
The project's scope also has to be constrained so that it doesn't get too complex and unwieldy, from an architectural perspective, a testing perspective, and from a usability perspective.
Plugins (widgets, shortcodes, theme packs, language packs, and third-party JavaScript integrations) as well as templates allow the community to add major features without needing to contribute to Hugo Blox itself.
Before submitting a PR:
- Test locally: Run
./scripts/view-starter-dev.sh academic-cv - Check formatting: Run
pnpm run lint:js(if you edited JS) - Update docs: If adding features, document them in the code and in the PR
- Add examples: Show how to use new features
- Write clear commit messages: Help future contributors understand changes
Every contribution matters โ whether it's fixing a typo, adding a translation, or building a new feature. You're helping thousands of researchers share their work with the world.
Welcome to the Hugo Blox community! ๐
Questions? Join our Discord or start a Discussion.
This project follows the Contributor Covenant Code of Conduct.
A Contributor License Agreement (CLA) is a standard best practice in professional open-source. It's a simple agreement that protects you (our contributor), our users, and the Hugo Blox project itself.
- It protects you: the CLA clarifies that you are entitled to contribute the code and that your contribution is provided "as is," without any warranty.
- It protects the project: it grants us the permanent legal rights needed to use your contribution as part of the project and defend the project from legal challenges.
- It enables our future: having a proper CLA allows us to confidently continue to enhance and support the Hugo Blox ecosystem.
This agreement doesn't change your ownership of your code; it simply grants us a clear license to use it as part of Hugo Blox.
By submitting a Pull Request to this repository, you agree to our Contributor License Agreement (CLA). Please ensure you have read and understood it.