From e71cac37f2e153a77e4dab47179afb48f475e542 Mon Sep 17 00:00:00 2001 From: Carlos Mogas da Silva Date: Fri, 14 May 2021 01:48:59 +0100 Subject: [PATCH] Add README file --- README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..9b86e0e --- /dev/null +++ b/README.md @@ -0,0 +1,66 @@ +### Description + +This theme component can be used to add support for [Matomo](https://matomo.org) to any website base on [Hugo](https://gohugo.io). Everything should work out of the box the way you like to configure it. I tried to use Matomo's official API and docs to do it and everything is working, but you guys might hit some corner case I didn't think of or need some functionality that isn't present and in that case, please open a pull request or open a issue explaining your problem. + +Also, I'm really not a Web developer (much less an Hugo "themer"), so, if you see something that could be done in some other way, or something that is totally wrong, please report it 😉. + +Translations are also welcomed and can be checked on the i18n folder. + +### Step to install + +- Clone repository + +`git submodule add https://code.r3pek.org/r3pek/hugo-matomo themes/hugo-matomo` + +- Add configuration to hugo config file + +On the `params` section of your config file, add the following structure: +``` + matomo: + enable: true + url: https://matomo.example.com + # Matomo's SiteID + id: 1 + # Link to page that will contain your privacy policy + policyurl: /privacy + # To track without javascript + noscript: true + # Disable cookies all together + disablecookies: false + # Require Cookie Consent before using them + requirecookieconsent: false + # Send a heart beet every X seconds so that on-page-times are more accurate + heartbeat: true + # Section specific to an iframe created on the Matomo server where it's possible to configure tracking + trackingstatus: + fontcolor: d0d0d0 + fontfamily: -apple-system,BlinkMacSystemFont,segoe ui,Roboto,Oxygen,Ubuntu,Cantarell,open sans,helvetica neue,sans-serif + fontsize: 18px + backgroundcolor: 1d1e20 +``` + +Every parameter should be very self explanatory but I made some comments to make them more understandable. + +- Update your site to load matomo + +Now, this really depends on the theme you're using but somehow you need to customize your site's ``. Just add the following code on the right place: + +`{{ partial "matomo_head" . }}` + +You should do the same for the footer of the page (that will display the Cookie Consent Popup) with the following code: + +`{{ partial "matomo_cookie_popup" . }}` + +- Create a privacy page + +As can be seen on the configuration options, you should have a privacy page describing what you do with the cookies you use. This component helps you create that page and gives the user choices to enable/disable the usage of cookies or the tracking altogether. + +Just create a `privacy.md` and place it on your posts folder. After that, on its content just add the following: + +`{{< matomo_privacy >}}` + +This should show the status of cookie usage and also if the user is being tracked or not, with the option to activate and deactivate either of them. + +--- + +If all went well, you should have everything setup and cookies used (or not) by your site and everything tracked on Matomo. \ No newline at end of file