A starter repo for building Hugo modules (by Daniel F. Dickinson)
ARCHIVED: This repo is no longer maintained and may have problems (including security issues) and may be out-of-date.
- Hugo module
- exampleSite (for demo deploys and/or documentation)
- Cache resources folder (exampleSite)
- HTML Validation
- Check internal links
- HTML Minification
- Module Demo Site allows showing Hugo Debug Tables by setting
debugTablesInFooter = truein the
Not a Theme
Note: This is not a theme, or even a theme component (although it could be the basis for one). This is a Hugo module skeleton, but with useful defaults for many of the files you will need in an actual module.
Using the Starter
Create new repo for module
- Download an archive of
- Latest version of the
- Or the latest release (currently v0.4.0):
- Latest version of the
- Create a directory (for example
- Extract the archive into this directory (note that the archive contains a top-level versioned directory that you don’t want. For example the README would be in
hugo-dfd-module-starter-v0.4.0/README.mdand you want it in
README.mdin your current directory. If you are using the tarball on Linux (including WSL), you can do
tar --strip-components=1 -xzf /path/to/your/source-archive.tar.gz).
git checkout -b main(this is optional)
git branch -D master(only execute if you use 7. above)
git lfs install
export HUGO_MODULE_REPLACEMENTS="github.com/danielfdickinson/hugo-dfd-module-starter -> $(pwd)"; cd exampleSite && hugo mod tidy(substituting your module name for
npm upgrade(this updates the Netlify plugins to latest versions, and fixes the
package-lock.jsoncurrent package name to your new module instead of
git add .
- Create a GitHub repo (e.g. in one case, I used
hugo-dfd-responsive-imageswhich resulted in a URL of https://github.com/danielfdickinson/hugo-dfd-responsive-images) (do not add a README, LICENSE and so on via GitHub as the repo already has all that, and you want a bare repository to which to push your local repo).
git remote add origin https://github.com/danielfdickinson/hugo-dfd-responsive-images.git
git push origin --set-upstream main
- After a few moments you should see the code for your repo on GitHub (in the web interface).
Connect repo with Netlify (for CI)
Prerequisite: You have already setup the Netlify app for you GitHub user or organization and are either allowing Netlify access to all your repositories or you have allowed Netlify access to this repo.
- Login to Netlify
- Select ‘New Site from Git’
- Select ‘GitHub’
- Select this repository from the list
- If you are using Git-LFS, Select ‘Advanced’ and add variable
- Select ‘Deploy Site’
- If you want to watch deploy progress, right click over the deploy and select “open in new tab” in your browser.
- If the deploy was not successful, correct any errors, commit and push, which should trigger another attempt at deploying.
- Once the deploy is successful, select ‘Site Settings’ and ‘Domain Management’
- Beside the default Netlify random-site-name.netlify.app name select ‘Options’ and ‘Edit site name’.
- Rename the site (will always end in .netlify.app).
- If you want a custom domain name and have a DNS service other than Netlify, then sign on to you provider and set a CNAME from your new-domain-name.example.com to your-netlify-domain-name.netlify.app.
- Trigger a deploy (otherwise the old name will interfere with the new name)
- If you have Netlify DNS you can skip this step
- Select ‘Add custom domain’
- Enter the custom domain name from above.
- Select add the domain.
- Under HTTPS select ‘Verify DNS configuration’
- Select ‘Provision certificate’
- You should now have an SSL protect version of the demo site for you repo.
- Tweak any other settings as you wish.
(Optional) Set up ‘branch protection’
- On GitHub, for you repo, go to Settings|Branches and enable ‘branch protection’ (Add rule, and enter ‘main’ as the branch)
- Check ‘Require status checks to pass before merging’
- Check ‘Require branches to be up to date before merging’
- Select ‘Require linear history’
- Select ‘Include administrators’
- Select ‘Create’
- In your repo create a new pull request branch (can have any name).
- In Netlify go to Site Setting and copy the ‘Site Badge’ code
- Paste site badge code into your README
- Save and commit the change.
- Push the new pull request branch to GitHub
- Create a new pull request from the branch on GitHub
- Once the deploy preview succeeds, open a new tab for ‘Settings|Branches’
- Select ‘Edit’ on you current ‘main’ branch protection rule
- Search for statuses using the name of your repo
- You want at least:
- All but ‘changed pages’ is recommended
- You want at least:
- Click ‘Save Changes’
- Close that tab
- Back on the Pull Request (PR), Select ‘Squash and Merge’
- Confirm ‘squash and merge’
- Delete branch
- Back in Netlify check the deploy status; it should succeed
- On GitHub check your repository’s README; it should show a Netlify status of ‘Success’
Develop Your Module
You are now ready to develop your module. Hack away!
Some useful Markdown for your module’s README
## Features TBD ## Basic Usage ### Importing the Module 1. The first step to making use of this module is to add it to your site or theme. In your configuration file: ``config.toml`` \```toml [module] [[module.imports]] path = "github.com/danielfdickinson/hugo-dfd-module-starter" \``` OR ``config.yaml`` \```yaml module: imports: - path: github.com/danielfdickinson/hugo-dfd-module-starter \``` 2. Execute \```bash hugo mod get github.com/danielfdickinson/hugo-dfd-module-starter hugo mod tidy \```