DEV Community

Cover image for Create a Hugo Theme from Scratch - IV
Xiaoliang Wang
Xiaoliang Wang

Posted on • Originally published at tomo.dev

Create a Hugo Theme from Scratch - IV

This is a series of blog posts documenting my journey of building a Hugo theme from scratch: https://github.com/tomowang/hugo-theme-tailwind. The series consists of four articles, this is the fourth one:

Continuous Integration

With the functionalities mentioned in previous articles completed, most of the coding work is done. However, as a project intended for others to use, there are still some additional tasks to handle.

As a Hugo theme repository, continuous integration can encompass several aspects, such as automated deployment of the example site and automated version releases based on git tags. Regarding the example site, the Hugo-generated static site can be easily published to GitHub Pages, and GitHub Actions provides actions to operate GitHub Pages. Here, I used three actions:

  1. actions/configure-github-pages - Configures GitHub Pages and retrieves some meta information, such as base_url
  2. actions/upload-pages-artifact - Uploads resources to GitHub Pages
  3. actions/deploy-pages - Deploys to GitHub Pages

The GitHub Pages related workflow requires additional permissions:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write
Enter fullscreen mode Exit fullscreen mode

Additionally, the Hugo compilation parameter --baseURL needs to use the meta information from GitHub Pages:

- name: Setup Pages
  id: pages
  uses: actions/configure-pages@v3

- name: Build with Hugo
  env:
    # For maximum backward compatibility with Hugo modules
    HUGO_ENVIRONMENT: production
    HUGO_ENV: production
  run: |
    hugo -s exampleSite --minify --gc --themesDir ../.. \
      --baseURL "${{ steps.pages.outputs.base_url }}/"
Enter fullscreen mode Exit fullscreen mode

The GitHub Actions code is placed in the .github/workflows/ directory and is triggered automatically by committing code.

hugo theme project github actions

hugo theme project github action detail

Moreover, I configured DNS resolution pointing the GitHub domain hugo-theme-tailwind.tomo.dev -> tomowang.github.io so that users can access the example site through https://hugo-theme-tailwind.tomo.dev.

Promotion

To reach a wider audience for the theme, the best way is to submit it to the official theme site. Hugo provides a GitHub repository to build the official theme site https://themes.gohugo.io/, and it also details the submission process.

  1. Specify the supported Hugo versions in the config.toml configuration file.
  2. Use the theme.toml file to describe some meta information about the theme, including name, copyright, tags, author, etc.
  3. A descriptive README document, which serves as the main page on GitHub and is used to display the theme details on the site.
  4. Theme screenshots and thumbnails with the following size requirements:
    1. Screenshot (screenshot.png or screenshot.jpg), with a minimum size of 1500×1000 pixels
    2. Thumbnail (tn.png or tn.jpg), with a minimum size of 900×600 pixels

After completing these steps, follow the git workflow to fork, modify, commit, and submit a PR to the official theme repository. I submitted my PR #391. Fortunately, the PR was quickly merged into the repository, and finally, the theme became accessible on the official theme site: https://themes.gohugo.io/themes/hugo-theme-tailwind/.

hugo theme tailwind

Other promotional channels include the official forum, where there is a dedicated section new theme for discussions about new themes. I created a new topic to introduce the theme.

hugo discourse new post

Additionally, some third-party theme sites collect data based on the topics configuration in the GitHub repository, such as builtatlightspeed. By configuring the hugo-theme topic in the GitHub repository, these theme sites can crawl and index the repository. The complete Topics I configured are theme hugo-theme hugo gohugo hugo-blog hugo-blog-theme tailwind tailwindcss tailwind-theme hugo-blog-template.

Currently, the theme is automatically listed on the following sites:

  1. https://statichunt.com/themes/hugo-theme-tailwind
  2. https://www.builtatlightspeed.com/theme/tomowang-hugo-theme-tailwind

Of course, there are other theme sites where you can submit through PRs, such as https://jamstackthemes.dev/.

Future

After submitting the theme to the community, some users tried it out and provided feedback, suggestions, and questions, which I addressed and handled one by one. Currently, the number of Stars on the GitHub repository is as follows:
GitHub Repo stars

Here is some data for reference:

When searching for the keyword "hugo theme tailwind" on Google, the theme page ranks quite high.

google search position

From Google Analytics, we can observe that the most traffic comes from the official theme site https://themes.gohugo.io, which is related to the Google search ranking.

google analytics traffic acquisition by source

This concludes this series of blog posts. Of course, the theme I created is relatively simple. If you are interested, you can try it out and provide valuable suggestions.

Top comments (0)