{"id":22690968,"url":"https://github.com/divinerites/plausible-hugo","last_synced_at":"2025-04-05T06:09:15.261Z","repository":{"id":40446032,"uuid":"284906733","full_name":"divinerites/plausible-hugo","owner":"divinerites","description":"Dead simple integration between plausible.io and gohugo.io","archived":false,"fork":false,"pushed_at":"2024-12-12T12:23:29.000Z","size":120,"stargazers_count":118,"open_issues_count":1,"forks_count":13,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-29T05:09:17.271Z","etag":null,"topics":["analytics","hugo","plausible-analytics","privacy"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/divinerites.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-04T07:19:03.000Z","updated_at":"2025-03-02T11:43:33.000Z","dependencies_parsed_at":"2025-01-07T22:16:15.009Z","dependency_job_id":null,"html_url":"https://github.com/divinerites/plausible-hugo","commit_stats":null,"previous_names":[],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/divinerites%2Fplausible-hugo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/divinerites%2Fplausible-hugo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/divinerites%2Fplausible-hugo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/divinerites%2Fplausible-hugo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/divinerites","download_url":"https://codeload.github.com/divinerites/plausible-hugo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247294540,"owners_count":20915340,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["analytics","hugo","plausible-analytics","privacy"],"created_at":"2024-12-10T01:08:55.540Z","updated_at":"2025-04-05T06:09:15.244Z","avatar_url":"https://github.com/divinerites.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# plausible-hugo : A theme component \u0026 Hugo module\n\nAccording to their web site, *\"Plausible Analytics, is a simple, open-source, lightweight (\u003c 1 KB) and privacy-friendly web analytics alternative to Google Analytics\"*\n\nAnd Hugo is *The world’s fastest framework for building websites*.\n\nThis Hugo theme component \u0026 module is a dead simple integration between [plausible.io](https://www.plausible.io?ref=github-plausible-hugo) and [gohugo.io](https://www.gohugo.io)\n\n---\n\n![GitHub version](https://img.shields.io/github/v/tag/divinerites/plausible-hugo?label=Version)\n![License](https://img.shields.io/github/license/divinerites/plausible-hugo)\n![Last commit](https://img.shields.io/github/last-commit/divinerites/plausible-hugo)\n\nPlease, consider **leaving a star on Github if you like it**. ![Github Stars](https://img.shields.io/github/stars/divinerites/plausible-hugo?style=social)\n\n[![Star History Chart](https://api.star-history.com/svg?repos=divinerites/plausible-hugo\u0026type=Date)](https://star-history.com/#divinerites/plausible-hugo\u0026Date)\n\n---\n\n## Usage is simple as 1-2-3\n\n1. Add this `plausible-hugo` component as a theme in your theme section in `config.toml`.\n1. Add a `[params.plausible]` section in your `config.toml` file.\n1. Call the partial `plausible_head.html` in your own `\u003chead\u003e` section.\n\n\u003e ### ***That's it ! It works***. Nothing more is needed\n\n### Mininum `config.toml` file\n\n```toml\ntheme = [\"plausible-hugo\"]  # Add this theme to your already existing other themes\n[params.plausible]\n  enable = true  # Whether to enable plausible tracking\n  domain = \"example.com\"  # Plausible \"domain\" name/id in your dashboard\n```\n\n### Example `\u003chead\u003e` html section\n\n```html\n\u003chead\u003e\n   ...\n   {{ partial \"plausible_head.html\" . }}\n   ...\n\u003c/head\u003e\n```\n\nYou can have a look at [the end of this file](#configuration-example-hugo-module-option) for a minimal working example as a hugo module.\n\n## Hugo Module\n\nYou also can use it as a versioned [Hugo Module](https://gohugo.io/hugo-modules/) if you prefer *and know how to do it*.\n\n**We strongly advise for this method**, as it will be simple and transparent to keep up with our version updates.\n\nIn this case, instead of declaring this as a theme, just add it as a hugo module.\n\n```toml\n[module]\n    [[module.imports]]\n        path = \"github.com/divinerites/plausible-hugo\"\n```\n\n# Using Plausible goals\n\n## 1 - Simple custom goals\n\nIf 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\n\nThen, add a straightforward call to those plausible function/goal where you need it in your gohugo code.\n\nThis is an example, if you want a plausible custom goal named `ClickOnTelephoneNumber`.\n\n### Snipplet example for `plausible_js.html`\n\n```js\nfunction ClickOnTelephoneNumber() {\n   plausible('ClickOnTelephoneNumber');\n}\n```\n\n### Example of integration in your html code\n\n```html\n\u003ca href=\"tel:+331234567890\"\n   onclick=\"ClickOnTelephoneNumber()\"\u003e\n+331234567890\n\u003c/a\u003e\n```\n\n## 2 -  Custom goals when entering a page\n\nYou 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\".\n\nJust add a front matter parameter `plausible_custom_goal` in this page.\n\nEach time you enter the page, your custom goal is reached.\n\n```yaml\n---\nplausible_custom_goal : \"MySpecialCustomGoal\"\n---\n```\n\n## 3 - Variable custom goals\n\n### Using variables for your Goal names\n\nFor more flexibility, do not forget that you can use any `{{ $variable }}` or `{{ .variable }}` for your Goal name.\n\nFor example, generate your goals using `/data/about.yml` or similar frontmatter, you get the idea.\n\nThen you’ll get 2 goals : `telephoneMobileAbout` \u0026 `telephoneHomeAbout`\n\n#### A - Example : `/data/about.yml`\n\n```yml\nabout:\n  enable : true\n  title : My title\n  about_item :\n  - title : An other item title\n    plausible : Mobile\n    phone : \"+33 1 23 45 67 89\"\n    content : lorem ipsum is better than nothing.\n  - title : An other item title 2\n    plausible : Home\n    phone : \"+33 9 87 65 43 21\"\n    content : lorem ipsum is better than nothing 2\n```\n\n#### B - Generate the calls in your `/partial/about.html` example\n\n```html\n{{- $data := index .Site.Data .Site.Language.Lang }}\n{{- if $data.about.about.enable }}\n   {{- range $data.about.about.about_item }}\n      \u003c!-- sanitize phone number for tel: function --\u003e\n      {{ $phone_ok := (replaceRE \"(\\\\s)\" \"\" .phone ) }}\n      \u003ca href=\"tel:{{ .phone_ok }}\"\n         onclick=\"telephone{{ .plausible | safeJS }}About()\"\u003e\n         {{ .phone }}\n      \u003c/a\u003e\n  {{- end }}\n{{- end }}\n```\n\n#### C - Sniplet for `plausible_js.html`\n\n```js\n{{- $data := index .Site.Data .Site.Language.Lang }}\n{{- if $data.about.about.enable }}\n   {{- range $data.about.about.about_item }}\n      function telephone{{ .plausible | safeJS }}About() {\n          plausible('telephone{{ .plausible | safeJS }}About');\n      }\n  {{- end }}\n{{- end }}\n```\n\n## 4 - Outbound Link custom goal\n\nIf you want to use the [Outbound Link](https://docs.plausible.io/outbound-link-click-tracking/) custom goal,\njust add the parameter `outbound_link` to your `params.plausible` section.\n\n```toml\n[params.plausible]\n  outbound_link = true\n```\n\n## 5 - File downloads tracking custom goal\n\nIf you want to use the [File downloads tracking](https://plausible.io/docs/file-downloads-tracking/) custom goal,\njust add the parameter `file_downloads` to your `params.plausible` section.\n\n```toml\n[params.plausible]\n  file_downloads = true\n```\n\n### 5.1 - Track a different file type\n\nIf you want to track different file types like `.sh` and `.run`, just add the parameter `file_downloads_types` to your `params.plausible` section.\n\n```toml\n[params.plausible]\n  file_downloads_types = \"sh,run\"\n```\n\n**Using the `file_downloads_types` parameter will override the default list and only your custom file type downloads will be tracked.**\n\n## 6 - 404 custom goal\n\nWe take care of the 404 pages for you.\n\nYou only have to [configure the goal in your Plausible settings](https://plausible.io/blog/track-404-errors) for them to show up on your dashboard : *Select `Custom event` as the goal trigger and enter this exact name: `404`*.\n\n## 7 - Hash-based routing\n\nIf you want to use [Hash-based routing](https://plausible.io/docs/hash-based-routing), just add the parameter `outbound_link` to your `params.plausible` section.\n\n```toml\n[params.plausible]\n  hash_based_routing = true\n```\n\n# Other options\n\n## 1 - Do not track certain pages\n\nYou can prevent certain pages from being tracked by adding `plausible_do_not_track: true` in the page Front Matter\n\n```yaml\n---\nplausible_do_not_track: true\n---\n```\n\n## 2 - Proxy for analytics and manage Adblockers\n\nSome adblockers/browsers block every tracking script, even privacy-first analytics like plausible.io\n\nYou can deal with this by [proxying the script](https://plausible.io/docs/proxy/introduction).\n\nIf you are hosting on Netlify, we have done the [main setup](https://plausible.io/docs/proxy/guides/netlify) for you.\n\n1 - Set `proxy_netlify` on your `config.toml`.\n\n```toml\n[params.plausible]\n   proxy_netlify = true\n```\n\n2 - Add the partial `plausible_redirects_netlify.html` in your `index.redir` file. So your final generated `_redirects` will take care of this proxying.\n\n```html\n# Netlify redirects from aliases\n{{ range $p := site.Pages -}}\n{{ range .Aliases }}\n{{  . | printf \"%-35s\" }} {{ $p.RelPermalink }} 301!\n{{ end -}}\n{{- end -}}\n\n{{ partial \"plausible_redirects_netlify.html\" . }}\n\n```\n\n3 - 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.\n\n```txt\n/misc/js/script.js https://plausible.io/js/script.js 200\n/misc/api/event https://plausible.io/api/event 200\n```\n\nIf you want outbound-links, use this line instead:\n\n```txt\n/misc/js/script.js https://plausible.io/js/plausible.outbound-links.js 200\n```\n\n## 2b - [DEPRECATED] Plausible custom subdomain\n\nUsing CNAME custom domains are now in legacy mode. **Please use the proxy method instead**.\n\n*If you [use your own subdomain](https://docs.plausible.io/custom-domain) for plausible.io, you just have to give the url in `custom_js_domain` parameter. This is optional.*\n\n```toml\n[params.plausible]\n   custom_js_domain = \"stats.example.com\"\n```\n\nNota : Since v1.10.0 you will receive a console warning when running hugo if you have this parameter.\n\n## 3 - Embed your Plausible.io dashboard in your Hugo site\n\nYou 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.\n\nFirst :\n\n- you need to generate a [**shared link** in your own Plausible dashboard](https://plausible.io/docs/embed-dashboard).\n- Do not give a theme or background color. You can do this with Hugo params.\n- For example it will generate `https://plausible.io/share/yourdomain?auth=AZE1234RTYUOP67`.\n\nThen, just put this value in a `.plausible.dash_link` parameter.\n\n```toml\n[params.plausible]\n  dash_link = \"https://plausible.io/share/yourdomain?auth=AZE1234RTYUOP67\"\n```\n\nYou also can add 2 parameter if you want, but this is optional  :\n\n- the theme you want (`light` / `dark` / `system`). Default is `light`.\n- the custom background color.\n  - Tip : You can set the background color as `transparent`.\n\n```toml\n[params.plausible]\n  dash_theme = \"dark\"\n  dash_bgcolor = \"#880011\"\n```\n\nThen just add this partial where you want your embeded Plausible dashboard.\n\n```html\n   ...\n   {{ partial \"plausible_dashboard.html\" .}}\n   ...\n```\n\n### Activating the embed dashboard\n\nThis embed dashboard feature **do not rely on `.plausible.enable`** variable.\n\nSo it will be shown if you simply add the `plausible_dashboard.html` template. Whatever is `plausible.enable`\n\nIn this case, for manually disabling the dashboard you can set `dash_disable` variable to `true`.\n\n```toml\n[params.plausible]\n  dash_disable = true\n```\n\n## 4 - Write public dashboard information in Web page source\n\nIf you made your [dashboard public](https://docs.plausible.io/visibility), *you may want* to write this url in your web page source, so people can find it more easily.\n\nJust add `public_dashboard = true` in your `config.toml` plausible section. **By default this option is set to `false`, so nothing is written by default**.\n\n```toml\n[params.plausible]\n   public_dashboard = true\n```\n\nAnd this will be written in your HTML source code. It also works for self hosting.\n\n```html\n\u003c!-- Plausible Analytics public dashboard URL : https://plausible.io/example.com --\u003e\n```\n\n## 5 - Self Hosting\n\nYou can define your self hosted domain address in `config.toml`.\n\nThis is optional, and `plausible.io` is used if this parameter is unset.\n\n```toml\n[params.plausible]\n   selfhosted_domain = \"myplausible.example.com\"  # Self-hosted plausible domain\n```\n\n## 6 - Plausible and Content-Security-Policy\n\nBe careful if you have some CSP in your headers, do not forget to **allow plausible domains** you use.\n\nYou can add directly the requested domain(s) to your existing `Content-Security-Policy`.\n\nOr use this `plausible_csp.html` partial in your `/layouts/index.headers`to generate for you the correct `_headers`, used by Netlify:\n\n### CSP example for `/layouts/index.headers`\n\n```headers\nContent-Security-Policy: [... existing stuff ...] {{ partial \"plausible_csp.html\" . }}\n```\n\nIn any case, in the HTML source code, you'll find a comment with the correct domain to add to your CSP.\n\n# Developping locally with plausible-hugo\n\n## 1 - Mode server\n\nWhen you're in `hugo mode server`, the call to plausible.io javascript is disable, so you can dev without bloating your statistics.\n\n## 2 - Debug mode\n\nWhen in mode server you could really need to test your code in real situation.\n\nIn this case, just add `debug = true` in your `[params.plausible]`.\nThe call to plausible.io javascript will be enable, so you can have everything working like in production.\n\n```toml\n[params.plausible]\n   debug = true  # debug mode\n```\n\n# Various\n\n## 1 - Check variables \u0026 module versions\n\nWe perform an automatic check if the right mandatory variables are fitting the right version.\n\nIf we found a problem, we abort your build with a clear message.\n\nYou will also receive warning message if you are using deprecated features.\n\nSo 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*.\n\n## 2 - Giving a star on github.com\n\nBy default we put a console friendly reminder to consider giving a star on github if you like this module.\n\nObviously you can disable this message, just by adding `gitstar = false` in your `params.plausible`.\n\n```toml\n[params.plausible]\n   gitstar = false\n```\n\n## 3 - Credits\n\n- Hugo : [www.gohugo.io](https://www.gohugo.io)\n- Plausible : [www.plausible.io](https://www.plausible.io?ref=github-plausible-hugo)\n  - Plausible documentation : [docs.plausible.io](https://docs.plausible.io?ref=github-plausible-hugo)\n\n# Configuration example *(hugo module option)*\n\n## config.toml\n\n```toml\n[module]\n   [[module.imports]]\n   path = \"github.com/divinerites/plausible-hugo\"\n\n[plausible]\nenable = true\ndomain = \"my-domain-id\"\noutbound_link = true\nfile_downloads = true\ndebug = false\ngitstar = false\n```\n\n## index.html\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chtml\u003e\n\u003chead\u003e\n   ...\n   {{ partial \"plausible_head.html\" . }}\n   ...\n\u003c/head\u003e\n\u003c/html\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdivinerites%2Fplausible-hugo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdivinerites%2Fplausible-hugo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdivinerites%2Fplausible-hugo/lists"}