Hugo module devel on Netlify
A starter repo for building Hugo modules (by Daniel F. Dickinson)
Status
ARCHIVED: This repo is no longer maintained and may have problems (including security issues) and may be out-of-date.
GitHub Repo
https://github.com/danielfdickinson/hugo-dfd-module-starter
Repository no longer exists, but the information below is still may prove useful for other purposes.
Features
- Hugo module
- exampleSite (for demo deploys and/or documentation)
- Netlify-ready
- Cache resources folder (exampleSite)
- HTML Validation
- Check internal links
- HTML Minification
- Module Demo Site allows showing Hugo Debug Tables by setting
debugTablesInFooter = true
in theexampleSite/config.toml
. - More…
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
hugo-dfd-module-starter
.- Latest version of the
main
branch: - Or the latest release (currently v0.4.0):
- Latest version of the
- Create a directory (for example
hugo-dfd-responsive-images
) cd hugo-dfd-responsive-images
- 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.md
and you want it inREADME.md
in your current directory. If you are using the tarball on Linux (including WSL), you can dotar --strip-components=1 -xzf /path/to/your/source-archive.tar.gz
). - Edit
README.md
,LICENSE
,go.mod
,netlify.toml
,exampleSite/config.toml
,exampleSite/content/about.md
,exampleSite/content/accessibility.md
, andexampleSite/content/docs/README.md
. git init
git checkout -b main
(this is optional)git branch -D master
(only execute if you use 7. above)- (optional)
git lfs install
export HUGO_MODULE_REPLACEMENTS="github.com/danielfdickinson/hugo-dfd-module-starter -> $(pwd)"; cd exampleSite && hugo mod tidy
(substituting your module name forgithub.com/danielfdickinson/hugo-dfd-module-starter
).npm upgrade
(this updates the Netlify plugins to latest versions, and fixes thepackage-lock.json
current package name to your new module instead ofhugo-dfd-module-starter
).git add .
git commit
- Create a GitHub repo (e.g. in one case, I used
hugo-dfd-responsive-images
which 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
GIT_LFS_ENABLED
with value1
. - 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’
- Wait
- 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:
- netlify/your-repo/deploy-preview
- 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
\```