From 5d831bbdd1df5116516bc72b1be335311fc62d17 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Wed, 22 Jul 2020 09:54:17 +0200 Subject: [PATCH] Added guide to set up site analytics --- docs/creating-your-site.md | 12 ++-- docs/setup/adding-site-analytics.md | 0 docs/setup/adding-social-links.md | 4 +- docs/setup/changing-the-logo-and-icons.md | 2 +- docs/setup/setting-up-site-analytics.md | 75 +++++++++++++++++++++++ mkdocs.yml | 2 +- 6 files changed, 86 insertions(+), 9 deletions(-) delete mode 100644 docs/setup/adding-site-analytics.md create mode 100644 docs/setup/setting-up-site-analytics.md diff --git a/docs/creating-your-site.md b/docs/creating-your-site.md index 67b8fe70e..d22b0fcd7 100644 --- a/docs/creating-your-site.md +++ b/docs/creating-your-site.md @@ -70,9 +70,9 @@ icons and much more: * [Changing the logo and icons][6] * [Setting up navigation][7] * [Setting up site search][8] -* [Adding a git repository][9] -* [Adding social links][10] -* [Adding site analytics][11] +* [Setting up site analytics][9] +* [Adding a git repository][10] +* [Adding social links][11] * [Adding a comment system][12] * [Adding an announcement bar][13] @@ -84,9 +84,9 @@ icons and much more: [6]: setup/changing-the-logo-and-icons.md [7]: setup/setting-up-navigation.md [8]: setup/setting-up-site-search.md - [9]: setup/adding-a-git-repository.md - [10]: setup/adding-social-links.md - [11]: setup/adding-site-analytics.md + [9]: setup/setting-up-site-analytics.md + [10]: setup/adding-a-git-repository.md + [11]: setup/adding-social-links.md [12]: setup/adding-a-comment-system.md [13]: setup/adding-an-announcement-bar.md diff --git a/docs/setup/adding-site-analytics.md b/docs/setup/adding-site-analytics.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/setup/adding-social-links.md b/docs/setup/adding-social-links.md index 88be25d9a..0f8c2a5d3 100644 --- a/docs/setup/adding-social-links.md +++ b/docs/setup/adding-social-links.md @@ -13,6 +13,8 @@ configured through `mkdocs.yml`. ## Configuration +### Social links + [:octicons-file-code-24: Source][1] · :octicons-milestone-24: Default: _none_ @@ -75,7 +77,7 @@ For each entry, the following fields are available: `name` -: :octicons-milestone-24: Default: _domain name from_ `link`, if available – +: :octicons-milestone-24: Default: _domain name from_ `link`_, if available_ – This field is used as the link's `title` attribute and can be set to a discernable name to improve accessibility: diff --git a/docs/setup/changing-the-logo-and-icons.md b/docs/setup/changing-the-logo-and-icons.md index fe0f819c6..273139918 100644 --- a/docs/setup/changing-the-logo-and-icons.md +++ b/docs/setup/changing-the-logo-and-icons.md @@ -55,7 +55,7 @@ theme: [4]: https://github.com/squidfunk/mkdocs-material/blob/master/src/base.html#L71 -### Emoji (icons) +### Icons [:octicons-file-code-24: Source][5] · [:octicons-workflow-24: Extension][6] diff --git a/docs/setup/setting-up-site-analytics.md b/docs/setup/setting-up-site-analytics.md new file mode 100644 index 000000000..696b283ba --- /dev/null +++ b/docs/setup/setting-up-site-analytics.md @@ -0,0 +1,75 @@ +--- +template: overrides/main.html +--- + +# Setting up site analytics + +As with any other service that is offered on the web, understanding how your +documentation is actually used can be an essential success factor. While +Material for MkDocs natively integrates with [Google Analytics][1], other +analytics services can be used, too. + + [1]: https://developers.google.com/analytics + +## Configuration + +### Site analytics + +[:octicons-file-code-24: Source][2] · :octicons-milestone-24: Default: _none_ + +After heading over to your [Google Analytics][1] account to [create a new +property][3] in order to obtain a new tracking id of the form `UA-XXXXXXXX-X`, +add it to `mkdocs.yml`: + +``` yaml +google_analytics: + - UA-XXXXXXXX-X + - auto +``` + +Publish and refresh your site, and you should see events bubbling up. + + [2]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/analytics.html + [3]: https://support.google.com/analytics/answer/1042508 + +### Site search analytics + +Besides basic page views, _site search_ can also be tracked to better understand +how people use your documentation and what they expect to find. To enable +search tracking: + +1. Go to your Google Analytics __admin settings__ +2. Select the property for the respective tracking code +3. Go to the __view settings__ tab. +4. Scroll down and enable __site search settings__ +5. Set the __query parameter__ to `q`. + +## Customization + +### Other analytics services + +[:octicons-file-code-24: Source][2] · +:octicons-mortar-board-24: Difficulty: _easy_ + +In order to integrate another analytics service provider offering an +asynchronous JavaScript-based tracking solution, you can [extend the theme][4] +and [override the `analytics` block][5]. + + [4]: ../customization.md#extending-the-theme + [5]: ../customization.md#overriding-blocks + +### Instant loading + +[:octicons-file-code-24: Source][2] · +:octicons-mortar-board-24: Difficulty: _easy_ + +If you're using [instant loading][6], you can use the `DOMContentSwitch` event +to listen for navigation events and register a page view event with: + +``` js +document.addEventListener("DOMContentSwitch", function() { + /* Register page event here */ +}) +``` + + [6]: setting-up-navigation.md#instant-loading diff --git a/mkdocs.yml b/mkdocs.yml index f48f497c2..06dc6955a 100755 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -138,9 +138,9 @@ nav: - Changing the logo and icons: setup/changing-the-logo-and-icons.md - Setting up navigation: setup/setting-up-navigation.md - Setting up site search: setup/setting-up-site-search.md + - Setting up site analytics: setup/setting-up-site-analytics.md - Adding a git repository: setup/adding-a-git-repository.md - Adding social links: setup/adding-social-links.md - - Adding site analytics: setup/adding-site-analytics.md - Adding a comment system: setup/adding-a-comment-system.md - Adding an announcement bar: setup/adding-an-announcement-bar.md #- Adding a landing page: setup/adding-a-landing-page.md