According to their web site, "Plausible Analytics, is a simple, open-source, lightweight (< 1 KB) and privacy-friendly web analytics alternative to Google Analytics"
And Hugo is The world’s fastest framework for building websites.
This Hugo theme component & module is a dead simple integration between plausible.io and gohugo.io
Please, consider leaving a star on Github if you like it.
- Add this
plausible-hugo
component as a theme in your theme section inconfig.toml
. - Add a
[params.plausible]
section in yourconfig.toml
file. - Call the partial
plausible_head.html
in your own<head>
section.
theme = ["plausible-hugo"] # Add this theme to your already existing other themes
[params.plausible]
enable = true # Whether to enable plausible tracking
domain = "example.com" # Plausible "domain" name/id in your dashboard
<head>
...
{{ partial "plausible_head.html" . }}
...
</head>
You can have a look at the end of this file for a minimal working example as a hugo module.
You also can use it as a versioned Hugo Module if you prefer and know how to do it.
We strongly advise for this method, as it will be simple and transparent to keep up with our version updates.
In this case, instead of declaring this as a theme, just add it as a hugo module.
[module]
[[module.imports]]
path = "github.com/divinerites/plausible-hugo"
If you want to use some custom goals, for each goal, you just have to add a snipplet in a partial named plausible_js.html
that you have to create in your site /partials
directory
Then, add a straightforward call to those plausible function/goal where you need it in your gohugo code.
This is an example, if you want a plausible custom goal named ClickOnTelephoneNumber
.
function ClickOnTelephoneNumber() {
plausible('ClickOnTelephoneNumber');
}
<a href="tel:+331234567890"
onclick="ClickOnTelephoneNumber()">
+331234567890
</a>
You can have a use case where you want a custom goal setup when you enter a certain page. So you can have more granularity than the classic "page goals".
Just add a front matter parameter plausible_custom_goal
in this page.
Each time you enter the page, your custom goal is reached.
---
plausible_custom_goal : "MySpecialCustomGoal"
---
For more flexibility, do not forget that you can use any {{ $variable }}
or {{ .variable }}
for your Goal name.
For example, generate your goals using /data/about.yml
or similar frontmatter, you get the idea.
Then you’ll get 2 goals : telephoneMobileAbout
& telephoneHomeAbout
about:
enable : true
title : My title
about_item :
- title : An other item title
plausible : Mobile
phone : "+33 1 23 45 67 89"
content : lorem ipsum is better than nothing.
- title : An other item title 2
plausible : Home
phone : "+33 9 87 65 43 21"
content : lorem ipsum is better than nothing 2
{{- $data := index .Site.Data .Site.Language.Lang }}
{{- if $data.about.about.enable }}
{{- range $data.about.about.about_item }}
<!-- sanitize phone number for tel: function -->
{{ $phone_ok := (replaceRE "(\\s)" "" .phone ) }}
<a href="tel:{{ .phone_ok }}"
onclick="telephone{{ .plausible | safeJS }}About()">
{{ .phone }}
</a>
{{- end }}
{{- end }}
{{- $data := index .Site.Data .Site.Language.Lang }}
{{- if $data.about.about.enable }}
{{- range $data.about.about.about_item }}
function telephone{{ .plausible | safeJS }}About() {
plausible('telephone{{ .plausible | safeJS }}About');
}
{{- end }}
{{- end }}
If you want to use the Outbound Link custom goal,
just add the parameter outbound_link
to your params.plausible
section.
[params.plausible]
outbound_link = true
If you want to use the File downloads tracking custom goal,
just add the parameter file_downloads
to your params.plausible
section.
[params.plausible]
file_downloads = true
If you want to track different file types like .sh
and .run
, just add the parameter file_downloads_types
to your params.plausible
section.
[params.plausible]
file_downloads_types = "sh,run"
Using the file_downloads_types
parameter will override the default list and only your custom file type downloads will be tracked.
We take care of the 404 pages for you.
You only have to configure the goal in your Plausible settings for them to show up on your dashboard : Select Custom event
as the goal trigger and enter this exact name: 404
.
If you want to use Hash-based routing, just add the parameter outbound_link
to your params.plausible
section.
[params.plausible]
hash_based_routing = true
You can prevent certain pages from being tracked by adding plausible_do_not_track: true
in the page Front Matter
---
plausible_do_not_track: true
---
Some adblockers/browsers block every tracking script, even privacy-first analytics like plausible.io
You can deal with this by proxying the script.
If you are hosting on Netlify, we have done the main setup for you.
1 - Set proxy_netlify
on your config.toml
.
[params.plausible]
proxy_netlify = true
2 - Add the partial plausible_redirects_netlify.html
in your index.redir
file. So your final generated _redirects
will take care of this proxying.
# Netlify redirects from aliases
{{ range $p := site.Pages -}}
{{ range .Aliases }}
{{ . | printf "%-35s" }} {{ $p.RelPermalink }} 301!
{{ end -}}
{{- end -}}
{{ partial "plausible_redirects_netlify.html" . }}
3 - If you do not already use the index.redir
system, you just can create a _redirects
file in your /static
folder and add those 2 lines below in this file.
/misc/js/script.js https://plausible.io/js/script.js 200
/misc/api/event https://plausible.io/api/event 200
If you want outbound-links, use this line instead:
/misc/js/script.js https://plausible.io/js/plausible.outbound-links.js 200
Using CNAME custom domains are now in legacy mode. Please use the proxy method instead.
If you use your own subdomain for plausible.io, you just have to give the url in custom_js_domain
parameter. This is optional.
[params.plausible]
custom_js_domain = "stats.example.com"
Nota : Since v1.10.0 you will receive a console warning when running hugo if you have this parameter.
You can embed your Plausible stats dashboard into on your hugo website using an iFrame. This is useful in case you want to showcase your stats.
First :
- you need to generate a shared link in your own Plausible dashboard.
- Do not give a theme or background color. You can do this with Hugo params.
- For example it will generate
https://plausible.io/share/yourdomain?auth=AZE1234RTYUOP67
.
Then, just put this value in a .plausible.dash_link
parameter.
[params.plausible]
dash_link = "https://plausible.io/share/yourdomain?auth=AZE1234RTYUOP67"
You also can add 2 parameter if you want, but this is optional :
- the theme you want (
light
/dark
/system
). Default islight
. - the custom background color.
- Tip : You can set the background color as
transparent
.
- Tip : You can set the background color as
[params.plausible]
dash_theme = "dark"
dash_bgcolor = "#880011"
Then just add this partial where you want your embeded Plausible dashboard.
...
{{ partial "plausible_dashboard.html" .}}
...
This embed dashboard feature do not rely on .plausible.enable
variable.
So it will be shown if you simply add the plausible_dashboard.html
template. Whatever is plausible.enable
In this case, for manually disabling the dashboard you can set dash_disable
variable to true
.
[params.plausible]
dash_disable = true
If you made your dashboard public, you may want to write this url in your web page source, so people can find it more easily.
Just add public_dashboard = true
in your config.toml
plausible section. By default this option is set to false
, so nothing is written by default.
[params.plausible]
public_dashboard = true
And this will be written in your HTML source code. It also works for self hosting.
<!-- Plausible Analytics public dashboard URL : https://plausible.io/example.com -->
You can define your self hosted domain address in config.toml
.
This is optional, and plausible.io
is used if this parameter is unset.
[params.plausible]
selfhosted_domain = "myplausible.example.com" # Self-hosted plausible domain
Be careful if you have some CSP in your headers, do not forget to allow plausible domains you use.
You can add directly the requested domain(s) to your existing Content-Security-Policy
.
Or use this plausible_csp.html
partial in your /layouts/index.headers
to generate for you the correct _headers
, used by Netlify:
Content-Security-Policy: [... existing stuff ...] {{ partial "plausible_csp.html" . }}
In any case, in the HTML source code, you'll find a comment with the correct domain to add to your CSP.
When you're in hugo mode server
, the call to plausible.io javascript is disable, so you can dev without bloating your statistics.
When in mode server you could really need to test your code in real situation.
In this case, just add debug = true
in your [params.plausible]
.
The call to plausible.io javascript will be enable, so you can have everything working like in production.
[params.plausible]
debug = true # debug mode
We perform an automatic check if the right mandatory variables are fitting the right version.
If we found a problem, we abort your build with a clear message.
You will also receive warning message if you are using deprecated features.
So it helps you updating your config.toml
in case we introduced some breaking changes in variables names between versions. It is rare, but it happened already.
By default we put a console friendly reminder to consider giving a star on github if you like this module.
Obviously you can disable this message, just by adding gitstar = false
in your params.plausible
.
[params.plausible]
gitstar = false
- Hugo : www.gohugo.io
- Plausible : www.plausible.io
- Plausible documentation : docs.plausible.io
[module]
[[module.imports]]
path = "github.com/divinerites/plausible-hugo"
[plausible]
enable = true
domain = "my-domain-id"
outbound_link = true
file_downloads = true
debug = false
gitstar = false
<!DOCTYPE html>
<html>
<head>
...
{{ partial "plausible_head.html" . }}
...
</head>
</html>