Site analytics¶

As with any other service offered on the web, understanding how your project documentation is actually used can be an essential success factor. Zensical natively integrates with Google Analytics and offers a customizable cookie consent and a feedback widget.

Configuration¶

Google Analytics¶

Zensical integrates natively with Google Analytics 4. If you already set up Google Analytics and have a property, enable it by adding the following lines to your configuration:

[project.extra.analytics]
provider = "google"
property = "G-XXXXXXXXXX"

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX

Was this page helpful?¶

A simple feedback widget can be included at the bottom of each page, encouraging users to give instant feedback whether a page was helpful or not. Add the following lines to your configuration:

[project.extra.analytics.feedback]
title = "Was this page helpful?"

[[project.extra.analytics.feedback.ratings]]
icon = "material/emoticon-happy-outline"
name = "This page was helpful"
data = 1
note = "Thanks for your feedback!"

[[project.extra.analytics.feedback.ratings]]
icon = "material/emoticon-sad-outline"
name = "This page could be improved"
data = 0
note = """
  Thanks for your feedback! Help us improve this page by
  using our <a href="..." target="_blank" rel="noopener">feedback form</a>.
"""

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX
    feedback:
      title: Was this page helpful?
      ratings:
        - icon: material/emoticon-happy-outline
          name: This page was helpful
          data: 1
          note: >-
            Thanks for your feedback!
        - icon: material/emoticon-sad-outline
          name: This page could be improved
          data: 0
          note: >-
            Thanks for your feedback! Help us improve this page by
            using our <a href="..." target="_blank" rel="noopener">feedback form</a>.

Both properties, title and ratings, are required. Note that it's possible to define more than two ratings, e.g. to implement a 1-5 star rating. You can add arbitrary HTML tags to the note which is shown after the user submitted the feedback, e.g., to link to a feedback form.

Since the feedback widget sends data to a third-party service, it is, of course, natively integrated with the cookie consent feature. If the user doesn't accept the analytics cookie, the feedback widget is not shown.

This feature is uses Google Analytics, which is why provider and property are also required. However, it's also possible to provide a custom feedback integration.

The following properties are available for each rating:

analytics.feedback.ratings.icon

This property must point to a valid icon path referencing any icon bundled with the theme, or the build will not succeed. Some popular combinations:

• + – material/emoticon-happy-outline + material/emoticon-sad-outline
• + – material/thumb-up-outline + material/thumb-down-outline
• + – material/heart + material/heart-broken

analytics.feedback.ratings.name

The value of this property is shown on user interaction (i.e. keyboard focus or mouse hover), explaining the meaning of the rating behind the icon.

analytics.feedback.ratings.data

The value of this property is sent as a data value with the custom event that is transmitted to Google Analytics¹ (or any custom integration).

analytics.feedback.ratings.note

The value of this property is shown after the user selected the rating. It may contain arbitrary HTML tags, which is especially useful to ask the user to provide more detailed feedback for the current page through a form. It's also possible to pre-fill forms with the URL and title of the current page by using the following placeholders:

• {url} – Page URL
• {title} – Page title

https://github.com/.../issues/new/?title=[Feedback]+{title}+-+{url}

In this example, when clicking the link, the user is redirected to the "new issue" form of your repository, with a pre-filled title including the path of the current document, e.g.:

[Feedback] Setting up site analytics – /setup/setting-up-site-analytics/

An alternative to GitHub issues is Google Forms.

Usage¶

Hide the feedback widget¶

The feedback widget can be hidden for a document with the front matter hide property. Add the following lines at the top of a Markdown file:

---
hide:
  - feedback
---

# Page title
...

Customization¶

Custom site analytics¶

In order to integrate another analytics service provider offering a JavaScript-based tracking solution, just follow the guide on theme extension and create a new partial in the overrides folder. The name of the partial is used to configure the custom integration:

<script>
  /* Add custom analytics integration here, e.g. */
  var property = "{{ config.extra.analytics.property }}" // (1)!

  /* Wait for page to load and application to mount */
  document.addEventListener("DOMContentLoaded", function() {
    location$.subscribe(function(url) {
      /* Add custom page event tracking here */ // (2)!
    })
  })
</script>

[project.extra.analytics]
provider: custom
property: foobar

extra:
  analytics:
    provider: custom
    property: foobar

You can add arbitrary key-value combinations to configure your custom integration. This is especially useful if you're sharing the custom integration across multiple repositories.

Custom site feedback¶

A custom feedback widget integration just needs to process the events that are generated by users interacting with the feedback widget with the help of some additional JavaScript:

document$.subscribe(function() {
  var feedback = document.forms.feedback
  if (typeof feedback === "undefined") return

  feedback.hidden = false // (1)!

  feedback.addEventListener("submit", function(ev) {
    ev.preventDefault()

    var page = document.location.pathname // (2)!
    var data = ev.submitter.getAttribute("data-md-value")

    console.log(page, data) // (3)!

    feedback.firstElementChild.disabled = true // (4)!

    var note = feedback.querySelector(
      ".md-feedback__note [data-md-value='" + data + "']"
    )
    if (note)
      note.hidden = false // (5)!
  })
}

[project]
extra_javascript = ["javascripts/feedback.js"]

extra_javascript:
  - javascripts/feedback.js