This chapter contains information only needed for development and maintaining the theme.
What to know if you want to contribute
What to know as a maintainer
Recipe to create various documentation screenshots
A new release can happen at any time from the main branch of the GitHub project without further acknowledgment. This makes it necessary that, every pushed set of changesets into the main branch must be self-contained and correct, resulting in a releasable version.
Stay simple for the user by focusing on the mantra “convention over configuration”.
At installation the site should work reasonable without (m)any configuration.
Stay close to the Hugo way.
Don’t use npm or any preprocessing, our contributors may not be front-end developers.
Document new features in the docs. This also contains entries to the What’s new page.
Don’t break existing features if you don’t have to.
Remove reported issue from the browser’s console.
Check for unnecessary whitespace and correct indention of your resulting HTML.
Write commit messages in the conventional commit format.
Following is an incomplete list of some of the used conventional commit types. Be creative.
| Common | Feature | Structure | Shortcodes |
|---|---|---|---|
| build | a11y | favicon | attachments |
| browser | archetypes | search | badge |
| chore | alias | menu | button |
| docs | generator | history | children |
| shortcodes | i18n | scrollbar | expand |
| theme | mobile | nav | icon |
| toc | include | ||
| rss | clipboard | math | |
| variant | syntaxhighlight | mermaid | |
| boxes | notice | ||
| openapi | |||
| piratify | |||
| siteparam | |||
| tabs |
This project tries to follow the semver policy - although not followed 100% in the past.
Usually an entry of Breaking on the What’s new page causes a new major release number.
All other entries on the What’s new page will increase the minor release number.
Releases resulting in a new major or minor number are called main release.
Releases containing bugfixes only, are only increasing the patch release number. Those releases don’t result in announcements on the What’s new page.
Entries on the What’s new page are checked and enforced during the version-release GitHub Action.
Issues are categorized and managed by assigning labels to it.
Once working on an issue, assign it to a fitting maintainer.
When done, close the ticket. Once an issue is closed, it needs to be assigned to next release milestone.
A once released ticket is not allowed to be reopened and rereleased in a different milestone. This would cause the changelog to be changed even for the milestone the issue was previously released in. Instead write a new ticket.
If a PR is merged and closed it needs an accompanied issue assigned to. If there is no issue for a PR, the maintainer needs to create one.
You can assign multiple PRs to one issue as long as they belong together.
Usually set the same labels and milestone for the PR as for the accompanied issue.
An issue that results in changesets must have exactly one of the following labels. This needs to be assigned latest before release.
| Label | Description | Changelog section |
|---|---|---|
| documentation | Improvements or additions to documentation | - |
| discussion | This issue was converted to a discussion | - |
| task | Maintenance work | Maintenance |
| feature | New feature or request | Features |
| bug | Something isn’t working | Fixes |
If the issue would cause a new main release due to semver semantics it needs one of the according labels and the matching badge on the What’s new page.
| Label | Description |
|---|---|
| change | Introduces changes with existing installations |
| breaking | Introduces breaking changes with existing installations |
If an issue does not result in changesets but is closed anyways, it must have exactly one of the following labels.
| Label | Description |
|---|---|
| duplicate | This issue or pull request already exists |
| invalid | This doesn’t seem right |
| support | Request for achieving a special goal |
| unresolved | No progress on this issue |
| update | A change in behavior after updat |
| wontchange | This will not be worked on |
You can assign one further label out of the following list to signal readers that development on an open issue is currently halted for different reasons.
| Label | Description |
|---|---|
| blocked | Depends on other issue to be fixed first |
| idea | A valuable idea that’s currently not worked on |
| undecided | No decision was made yet |
| helpwanted | Great idea, send in a PR |
| needsfeedback | Further information is needed |
If the issue is not caused by a programming error in the themes own code, you can label the causing program or library.
| Label | Description |
|---|---|
| asciidoc | This is a topic related to processing of AsciiDoc |
| browser | This is a topic related to the browser but not the theme |
| device | This is a topic related to a certain device |
| hugo | This is a topic related to Hugo itself but not the theme |
| mermaid | This is a topic related to Mermaid itself but not the theme |
Git Hooks are used to automate some tasks. They are stored in the .githooks root folder.
Documentation for each hook is contained in each file.
At least the pre-commit hook is required, as it updates the version number on each commit. This helps to help debugging of user related issues.
A release is based on a milestone named like the release itself - just the version number, eg: 1.2.3. It’s in the maintainers responsibility to check semver semantics of the milestone’s name prior to release and change it if necessary.
Making releases is automated by the version-release GitHub Action. It requires the version number of the milestone that should be released. The release will be created from the main branch of the repository.
Treat released milestones as immutable. Don’t rerelease an already released milestone. An already released milestone may already been consumed by your users.
During execution of the action a few things are checked. If a check fails the action fails, resulting in no new release. You can correct the errors afterwards and rerun the action.
The following checks will be enforced
introduction/releasenotes/<major>/<minor>.en.mdAfter a successful run of the action
introduction/changelog/<major>/<minor>/<patch>.<lang>.md is created for english and piratish, including missing generic upper level filesCHANGELOG.md is updatedintroduction/releasenotes/<major>/<minor>.en.md are updated, including release version and release date<meta generator> is updated1.2.3), the main version number (eg. 1.2.x) and the major version number (eg. 1.x)<meta generator> is updated to a temporary and committed (this helps to determine if users are running directly on the main branch or are using releases)Sometimes screenshots need to be redone. This page explains how to create the different screenshots, tools and settings
Creation:
Content:
A meaningful full-screen screenshot of an interesting page.
The content should be:
Used by:
images/screenshot.png)images/tn.png)Page URL: Screenshot Link
Creation:
images/screenshot.pngimages/tn.pngRemarks:
The locations are mandatory due to Hugo’s theme site builder.
Preview images/screenshot.png:
Preview images/tn.png:
Content:
Show the Demo Screenshot page on different devices and different themes. Composition of the different device screenshots into a template.
The content should be:
Used by:
Page URL: Hero Image Link
Creation:
images/hero.pngPreview images/hero.png:
The feature images for the shortcodes are generated automatically via a Node.js script.
It is located in the repository inside of the /tools directory. All following commands need to be executed from this directory.
To recreate the screenshots
npm installnpm run screenshots