Add README file

2021-05-14 01:48:59 +01:00 · 2021-05-14 01:48:59 +01:00 · e71cac37f2
commit e71cac37f2
parent 3dc6b8c0cd
1 changed files with 66 additions and 0 deletions
--- a/README.md
+++ 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 `<head></head>`. 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.