feat(LycheeOrg/Lychee#1896): Add guide for analytics tools

.gitignore

@@ -1,3 +1,4 @@
 __pycache__/
 build/*
-.vscode
+.vscode/
+.idea/

docs/external_tracking.md

@@ -0,0 +1,111 @@
+This guide will help you to set up Matomo, Google Analytics or other analytics tools with Lychee.
+
+## Set up for Matomo
+
+> ⚠️ Make sure to use your actual values for domain and siteId
+
+### Allow loading tracking script
+
+Set the following env vars:
+
+```ini
+SECURITY_HEADER_SCRIPT_SRC_ALLOW=https://analytics.example.com/matomo.js
+SECURITY_HEADER_CSP_CONNECT_SRC=https://analytics.example.com/matomo.js
+```
+
+### Add custom JavaScript
+
+Add the following to Settings > Custom JS
+
+```javascript
+var _paq = window._paq = window._paq || [];
+_paq.push(['trackPageView']);
+_paq.push(['enableLinkTracking']);
+(function () {
+    var u = "https://analytics.example.com/";
+    _paq.push(['setTrackerUrl', u + 'matomo.php']);
+    _paq.push(['setSiteId', '<site-id>']);
+    var d = document, g = d.createElement('script'), s = d.getElementsByTagName('script')[0];
+    g.async = true;
+    g.src = u + 'matomo.js';
+    s.parentNode.insertBefore(g, s);
+})();
+
+navigation.addEventListener("navigate", function (e) {
+    _paq.push(['setDocumentTitle', document.title]);
+    _paq.push(['trackPageView']);
+});
+```
+
+## Set up for Google Analytics
+
+> ⚠️ Make sure to replace &lt;your-tracking-id&gt; with the actual value
+
+### Allow loading tracking script
+
+Set the following env vars:
+
+```ini
+SECURITY_HEADER_SCRIPT_SRC_ALLOW=https://www.googletagmanager.com/gtag/js?id=<your-tracking-id>
+SECURITY_HEADER_CSP_CONNECT_SRC=https://www.googletagmanager.com/gtag/js?id=<your-tracking-id>
+```
+
+### Add custom JavaScript
+
+Add the following to Settings > Custom JS
+
+```javascript
+(function () {
+  var u = "https://www.googletagmanager.com/gtag/js";
+  var d = document, g = d.createElement('script'), s = d.getElementsByTagName('script')[0];
+  g.async = true;
+  g.src = u + '?id=<your-tracking-id>';
+  s.parentNode.insertBefore(g, s);
+})();
+
+window.dataLayer = window.dataLayer || [];
+function gtag(){
+    dataLayer.push(arguments);
+}
+
+function trackPageView() {
+  gtag('event', 'page_view', {
+    page_title: document.title,
+    page_location: window.location
+  });
+}
+
+gtag('js', new Date());
+gtag('config', '<your-tracking-id>', {
+  send_page_view: false
+});
+trackPageView();
+
+navigation.addEventListener("navigate", function (e) {
+  trackPageView()
+});
+```
+
+## Other tools / custom tracking
+
+### Configuration adjustments
+
+To make the frontend load the tracking script you need to change two environment variables:
+
+- SECURITY_HEADER_SCRIPT_SRC_ALLOW to modify the
+  header [`CSP: srcript-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src)
+- SECURITY_HEADER_CSP_CONNECT_SRC to modify the
+  header [`CSP: connect-src`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/connect-src)
+
+### Track view changes
+
+Add your custom tracking code to Settings > Custom JS
+
+As Lychee uses history based routing you need to track page changes on the `navigate event` like this:
+
+```javascript
+navigation.addEventListener("navigate", function (e) {
+    // track page logic goes here
+});
+```
+

gen.py

@@ -12,18 +12,18 @@
 def numberify_version(v):
     v = v.split('.')
     if len(v[1]) < 2:
-        v[1] = '0'+v[1]
+        v[1] = '0' + v[1]
     if len(v[2]) < 2:
-        v[2] = '0'+v[2]
+        v[2] = '0' + v[2]
     return "".join(v)
 
 
 def generate_base():
-    version = urllib.request.urlopen(
-        "https://raw.githubusercontent.com/LycheeOrg/Lychee/master/version.md").read().decode("utf-8")
+    version_file_url = "https://raw.githubusercontent.com/LycheeOrg/Lychee/master/version.md"
+    version = urllib.request.urlopen(version_file_url).read().decode("utf-8")
     version = version.strip()
 
-    print(bcolors.YELLOW + 'version number: '  + bcolors.NORMAL + version+'\n')
+    print(f'{bcolors.YELLOW}version number: {bcolors.NORMAL} {version}\n')
 
     head = read('template/head.tpl')
     index = read('template/index.tpl')
@@ -42,11 +42,14 @@ def generate_base():
     update_full = update % numberify_version(version)
 
     save("build/index.html", index_full)
-    print(bcolors.GREEN + 'index' + bcolors.NORMAL + " generated.")
+    print(f'{bcolors.GREEN}index{bcolors.NORMAL} generated.')
+
     save("build/support.html", support_full)
-    print(bcolors.GREEN + 'support' + bcolors.NORMAL + " generated.")
+    print(f'{bcolors.GREEN}support{bcolors.NORMAL} generated.')
+
     save("build/update.json", update_full)
-    print(bcolors.GREEN + 'update' + bcolors.NORMAL + " generated.")
+    print(f'{bcolors.GREEN}update{bcolors.NORMAL} generated.')
+
     print("")
 
 
@@ -71,6 +74,7 @@ def generate_base():
 pages_title['settings'] = 'Settings'
 pages_title['keyboard'] = 'Keyboard Shortcuts'
 pages_title['advanced-setups'] = 'Advanced Setups'
+pages_title['external_tracking'] = "External tracking with Matomo, Google Analytics & Co"
 
 pages_title['faq_general'] = 'General'
 pages_title['faq_installation'] = 'Installation, migration, upgrade, update'
@@ -88,38 +92,39 @@ def generate_base():
 structure += [['Getting Started',
                ['installation', 'configuration', 'docker', 'update', 'upgrade']]]
 structure += [['Advanced Topics',
-               ['settings', 'keyboard', 'advanced-setups']]]
+               ['settings', 'keyboard', 'advanced-setups', 'external_tracking']]]
 structure += [['Frequently Asked Question',
                ['faq_general', 'faq_installation', 'faq_troubleshooting']]]
 structure += [['Contributing',
                ['contributions', 'api', 'architecture', 'structure', 'frontend', 'livewire']]]
 
+
 def gen_github_link(page):
     html = '<blockquote><p>{tip} Caught a mistake or want to contribute to the documentation?&nbsp;'
-    html += '<a href="https://github.com/LycheeOrg/LycheeOrg.github.io/tree/master/docs/' + page + '.md">Edit this page on Github!</a></p></blockquote>'
+    html += f'<a href="https://github.com/LycheeOrg/LycheeOrg.github.io/tree/master/docs/{page}.md">Edit this page on Github!</a></p></blockquote>'
     return html
 
-def gen_sidebar(page):
 
+def gen_sidebar(page):
     html = ''
     for section in structure:
         html += "<li class='sub--on'>\n"
-        html += "<h2>{}</h2>\n".format(section[0])
+        html += f"<h2>{section[0]}</h2>\n"
         html += "<ul>\n"
         for pages_name in section[1]:
             active = ''
             if pages_name == page:
                 active = " class='active'"
-            html += "<li{active}><a href='{page}.html'>{title}</a></li>\n".format(
-                active=active, page=pages_name, title=pages_title[pages_name])
+            html += f"<li{active}><a href='{pages_name}.html'>{pages_title[pages_name]}</a></li>\n"
         html += "</ul>\n"
 
     return html
 
+
 def generate_doc():
     for page_name in pages_title:
         page_title = pages_title[page_name]
-        text = read('docs/' + page_name + '.md')
+        text = read(f'docs/{page_name}.md')
         if page_name == 'settings':
             html = md2.convert(text)
             toc = md2.toc[17:-7]
@@ -131,37 +136,36 @@ def generate_doc():
         html += gen_github_link(page_name)
 
         html = frame.format(content=html, title=page_title, toc=toc, aside=aside)
-        save('build/docs/' +  page_name + '.html', html)
-        print(bcolors.GREEN + page_name + bcolors.NORMAL + " generated.")
+        save(f'build/docs/{page_name}.html', html)
+        print(f'{bcolors.GREEN} {page_name}{bcolors.NORMAL} generated.')
 
     shutil.copy('build/docs/installation.html', 'build/docs/index.html')
 
 
-
 def check():
     repo = Repo.init('.')
     if repo.is_dirty():  # check the dirty state
         for item in repo.index.diff(None):
-            print(bcolors.RED + item.a_path + " changed." + bcolors.NORMAL)
+            print(f'{bcolors.RED} {item.a_path}  changed.{bcolors.NORMAL}')
         print("")
-        print(bcolors.RED + "Please commit them." + bcolors.NORMAL)
+        print(f'{bcolors.RED}Please commit them. {bcolors.NORMAL}')
         return True
     else:
-        print(bcolors.GREEN + "No changes detected." + bcolors.NORMAL)
+        print(f'{bcolors.GREEN}No changes detected.{bcolors.NORMAL}')
         return False
 
 
-
 def test_main():
     generate_base()
     generate_doc()
-    assert(not check())
+    assert (not check())
 
 
 def main():
     generate_base()
     generate_doc()
     check()
 
+
 if __name__ == '__main__':
     main()