TelemetryDeck · winsmith · May 4, 2026 · May 4, 2026 · May 4, 2026 · May 4, 2026
diff --git a/.github/workflows/azure-static-web-apps-purple-bush-012fe8010.yml b/.github/workflows/azure-static-web-apps-purple-bush-012fe8010.yml
@@ -0,0 +1,60 @@
+name: Azure Static Web Apps CI/CD
+
+on:
+  push:
+    branches:
+      - feature/zensible
+  pull_request:
+    types: [opened, synchronize, reopened, closed]
+    branches:
+      - feature/zensible
+
+jobs:
+  build_and_deploy_job:
+    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
+    runs-on: ubuntu-latest
+    name: Build and Deploy Job
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          submodules: true
+          lfs: false
+      - name: Replace TelemetryDeck App ID
+        env:
+          TELEMETRYDECK_APP_ID: ${{ secrets.TELEMETRYDECK_APP_ID }}
+        run: |
+          sed -i "s|#TELEMETRYDECK_APP_ID#|${TELEMETRYDECK_APP_ID}|g" overrides/partials/integrations/analytics/telemetrydeck.html
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - run: pip install zensical
+      - run: zensical build --clean
+      - name: Generate llms.txt and ship raw markdown
+        run: python3 scripts/build_llms.py
+      - name: Build And Deploy
+        id: builddeploy
+        uses: Azure/static-web-apps-deploy@v1
+        with:
+          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_PURPLE_BUSH_012FE8010 }}
+          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
+          action: "upload"
+          ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
+          # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
+          app_location: "site"
+          api_location: ""
+          skip_app_build: true
+          skip_api_build: true
+          output_location: ""
+          ###### End of Repository/Build Configurations ######
+
+  close_pull_request_job:
+    if: github.event_name == 'pull_request' && github.event.action == 'closed'
+    runs-on: ubuntu-latest
+    name: Close Pull Request Job
+    steps:
+      - name: Close Pull Request
+        id: closepullrequest
+        uses: Azure/static-web-apps-deploy@v1
+        with:
+          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_PURPLE_BUSH_012FE8010 }}
+          action: "close"
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,31 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - master
+      - main
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v6
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: 3.x
+      - run: pip install zensical
+      - run: zensical build --clean
+      - name: Generate llms.txt and ship raw markdown
+        run: python3 scripts/build_llms.py
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+      - uses: actions/deploy-pages@v5
+        id: deployment
diff --git a/README.md b/README.md
@@ -5,3 +5,20 @@
 We're incredibly grateful for pull requests or issues that improve things or let us know about errata and missing or unclear bits of information! <3
 
 Check out `articles/documentation.md` for an overview of how documentation pages are formatted.
+
+
+## Local Development
+
+We use Python `pip`. You can follow the setups at https://zensical.org/docs/get-started/#installation for the initial setup.
+
+Note: Make sure the Python version is recent e.g. 3.14 or later (`python3 --version`).
+
+## LLM and agent friendly output
+
+Every page is also published as raw Markdown alongside the rendered HTML. After `zensical build`, run `python3 scripts/build_llms.py` to:
+
+- copy each source `.md` from `docs/` into the corresponding location in `site/` (so `https://docs.telemetrydeck.com/articles/insights.md` returns the source for `/articles/insights/`),
+- write `site/llms.txt` following the [llms.txt](https://llmstxt.org) convention,
+- write `site/llms-full.txt` containing every page concatenated for one-shot ingestion.
+
+Both deploy workflows run this step automatically after the Zensical build.
diff --git a/docs.11tydata.js b/docs.11tydata.js
diff --git a/api/api-query-from-insight.md → docs/api/api-query-from-insight.md b/api/api-query-from-insight.md → docs/api/api-query-from-insight.md
@@ -6,11 +6,9 @@ description: Using the TelemetryDeck API, you can retrieve the query that is use
 lead: Using the TelemetryDeck API, you can retrieve the query that is used in an insight
 ---
 
-{% notewarning "Paid plans only" %}
+!!! warning "Paid plans only"
 
-API access — including retrieving an insight's query — is available on TelemetryDeck's paid plans. If your organization is on the free plan, upgrade your plan first and you'll be able to generate a personal access token and use the API.
-
-{% endnotewarning %}
+    API access — including retrieving an insight's query — is available on TelemetryDeck's paid plans. If your organization is on the free plan, upgrade your plan first and you'll be able to generate a personal access token and use the API.
 
 ## Authorization
 

diff --git a/api/api-run-query.md → docs/api/api-run-query.md b/api/api-run-query.md → docs/api/api-run-query.md
@@ -7,11 +7,9 @@ lead: Using the TelemetryDeck API, you can run a query and retrieve its results
 order: 2
 ---
 
-{% notewarning "Paid plans only" %}
+!!! warning "Paid plans only"
 
-API access — including running queries — is available on TelemetryDeck's paid plans. If your organization is on the free plan, upgrade your plan first and you'll be able to generate a personal access token and run queries.
-
-{% endnotewarning %}
+    API access — including running queries — is available on TelemetryDeck's paid plans. If your organization is on the free plan, upgrade your plan first and you'll be able to generate a personal access token and run queries.
 
 ## Authorization
 

diff --git a/api/api-token.md → docs/api/api-token.md b/api/api-token.md → docs/api/api-token.md
@@ -7,11 +7,9 @@ lead: To interact with the TelemetryDeck API, you need a personal access token (
 order: 1
 ---
 
-{% notewarning "Paid plans only" %}
+!!! warning "Paid plans only"
 
-Personal access tokens are available on TelemetryDeck's paid plans. If your organization is on the free plan, upgrade your plan first and the feature will become available in the dashboard.
-
-{% endnotewarning %}
+    Personal access tokens are available on TelemetryDeck's paid plans. If your organization is on the free plan, upgrade your plan first and the feature will become available in the dashboard.
 
 ## Generating a Personal Access Token
 

diff --git a/api/api.json → docs/api/api.json b/api/api.json → docs/api/api.json
diff --git a/api/insights-reference.md → docs/api/insights-reference.md b/api/insights-reference.md → docs/api/insights-reference.md
diff --git a/api/signals-reference.md → docs/api/signals-reference.md b/api/signals-reference.md → docs/api/signals-reference.md
diff --git a/articles/anonymization-how-it-works.md → docs/articles/anonymization-how-it-works.md b/articles/anonymization-how-it-works.md → docs/articles/anonymization-how-it-works.md
@@ -8,7 +8,7 @@
 lead: We take user privacy seriously. To ensure the privacy of our users, we use various techniques to anonymize user data. One of the ways we do this is by using a double hashing technique to anonymize user identifiers.
 searchEngineTitle: How TelemetryDeck anonymizes user data privacy-friendly
 searchEngineDescription: TelemetryDeck anonymizes user data, by double hashing and salting IDs, to ensure anonymity and protect user privacy while still providing valuable insights.
-headerImage: /docs/images/anonymization-display-image.jpg
+headerImage: /assets/anonymization-display-image.jpg
 ---
 
 ## Methodology
@@ -19,7 +19,7 @@
 
 **Check out why [App Store Connect is not enough](https://www.youtube.com/watch?v=4_WqJGPzgmY) to protect user data!**
 
-[![Compare TelemetryDeck and App Store Connect for Analytics](/docs/images/yt-app-store-connect.png)](https://www.youtube.com/watch?v=4_WqJGPzgmY)
+[![Compare TelemetryDeck and App Store Connect for Analytics](/assets/yt-app-store-connect.png)](https://www.youtube.com/watch?v=4_WqJGPzgmY)
 
 ## User identifiers
 
@@ -35,7 +35,7 @@
 
 **Check out our [YouTube Channel](https://www.youtube.com/watch?v=4sQcZoi21nU) for a deeper dive into our anonymization process!**
 
-[![The Benefits of TelemetryDeck For Privacy Focused App Analytics](/docs/images/yt-app-analytics.png)](https://www.youtube.com/watch?v=4sQcZoi21nU)
+[![The Benefits of TelemetryDeck For Privacy Focused App Analytics](/assets/yt-app-analytics.png)](https://www.youtube.com/watch?v=4sQcZoi21nU)
 
 ## Conclusion
 

diff --git a/articles/app-privacy-report.md → docs/articles/app-privacy-report.md b/articles/app-privacy-report.md → docs/articles/app-privacy-report.md
diff --git a/articles/app-tracking-transparency.md → docs/articles/app-tracking-transparency.md b/articles/app-tracking-transparency.md → docs/articles/app-tracking-transparency.md
diff --git a/articles/apple-app-privacy.md → docs/articles/apple-app-privacy.md b/articles/apple-app-privacy.md → docs/articles/apple-app-privacy.md
@@ -16,7 +16,7 @@ Since TelemetryDeck's analytics are private by default, you can include this inf
 
 This means your app will get an excellent privacy rating.
 
-![A screenshot of Apple's Privacy Overview](/docs/images/privacy-overview.png)
+![A screenshot of Apple's Privacy Overview](/assets/privacy-overview.png)
 
 ## How do I start?
 
@@ -34,14 +34,12 @@ In the second screen, scroll down until you see the **Identifiers** section.
 
 In TelemetryDeck's **default mode**, with no user identifier specified, check the **Device ID** checkmark. This is what identifies individual users to TelemetryDeck.
 
-{% noteinfo "Other Types of Identifiers" %}
+!!! warning "Other Types of Identifiers"
 
-In case you use TelemetryDeck in a more advanced way where you supply a custom user identifier, you'll need to think about this for a second:
+    In case you use TelemetryDeck in a more advanced way where you supply a custom user identifier, you'll need to think about this for a second:
 
-- If you instead specify a User Identifier such as email address or username to TelemetryDeck, check instead the **User ID** checkmark. The identifier is only transmitted as a hash, but it still counts as a user identifier.
-- If you instead are purposefully disabling user tracking by handing the same string to TelemetryDeck for each user, you don't need to check any of the checkboxes in the **Identifiers** section.
-
-{% endnoteinfo %}
+    - If you instead specify a User Identifier such as email address or username to TelemetryDeck, check instead the **User ID** checkmark. The identifier is only transmitted as a hash, but it still counts as a user identifier.
+    - If you instead are purposefully disabling user tracking by handing the same string to TelemetryDeck for each user, you don't need to check any of the checkboxes in the **Identifiers** section.
 
 ### Usage Data
 

diff --git a/articles/articles.json → docs/articles/articles.json b/articles/articles.json → docs/articles/articles.json
diff --git a/...if-users-upgrade-to-latest-app-version.md → ...if-users-upgrade-to-latest-app-version.md b/...if-users-upgrade-to-latest-app-version.md → ...if-users-upgrade-to-latest-app-version.md
diff --git a/articles/create-custom-dashboards.md → docs/articles/create-custom-dashboards.md b/articles/create-custom-dashboards.md → docs/articles/create-custom-dashboards.md
@@ -16,7 +16,7 @@ order:
 
 To create a dashboard for your insights, go to your [TelemetryDeck dashboard](https://dashboard.telemetrydeck.com/), navigate to `Dashboards` and look at the left sidebar. Here you can find the `New Dashboard` button. Create a _New Dashboard_, give your dashboard a name and then click _Create_. You now have a new insight dashboard in your sidebar!
 
-![Location of the "Create New Dashboard" Button](/docs/images/location-create-dashboard.png)
+![Location of the "Create New Dashboard" Button](/assets/location-create-dashboard.png)
 
 ## Share your dashboards with your organization
 
@@ -31,20 +31,20 @@ You can also share specific dashboards with the members of your organization. To
 
 Now let's **create** an insight. While in your newly created dashboard, navigate to the `Actions` drop down button on the top-right side. Click the _Create new Insight_ button and give your new insight a name. Please choose from one of our convenient templates! The insight will be automagically ✨ generated for you. If needed, you can also change the display mode, title, query type, and more - even after creating it.
 
-![Location of the "Create New Insight" Button](/docs/images/create-new-insight.png)
+![Location of the "Create New Insight" Button](/assets/create-new-insight.png)
 
 
 You can create a bunch of insights inside your dashboards and thus, combine thematically related charts of your insights. And you're able to resize your charts to regular-sized `Compact` cards or big `Wide` cards.
 
 To **delete** insights from a dashboard, click on the insights' name. Go to `Actions` in the top right corner, just delete the current insight by clicking on "Delete Insight".
 
-![Location of the "Delete Insight" Button](/docs/images/location-edit-insight.png)
+![Location of the "Delete Insight" Button](/assets/location-edit-insight.png)
 
 ### Rename your dashboard
 
 Not happy with the name given to your dashboard? No problem - you can change it quickly! Click on the dashboard whose name you want to change. Then hover over your dashboard name, and click to edit. Save your changes after you are done editing - your dashboard now has a new name.
 
-![Location of the "Rename Dashboard" Button](/docs/images/edit-dashboard-name.png)
+![Location of the "Rename Dashboard" Button](/assets/edit-dashboard-name.png)
 
 ### Delete your dashboard
 

diff --git a/articles/decide-to-drop-ios-version.md → docs/articles/decide-to-drop-ios-version.md b/articles/decide-to-drop-ios-version.md → docs/articles/decide-to-drop-ios-version.md
@@ -27,7 +27,7 @@ The TelemetryDeck SDK by default tries to collect data about the user's operatin
 
 To find out which percentage of your users are using a certain OS version, use a **Breakdown Insight** (also known as a **Top N Insight**). Then you'll have multiple options for the breakdown key.
 TelemetryDeck provides pre-built dashboards, among others the Top N Insight just described:
-![Screenshot SystemVersion](/docs/images/Screenshot_SystemVersion.png)
+![Screenshot SystemVersion](/assets/Screenshot_SystemVersion.png)
 You can switch between `majorMinorVersion` and `majorVersion` in the chart. Below we come back to the difference with recommendations what to use for this purpose.
 
 As an orientation beyond your app we also want to point out our monthly updated [surveys](https://telemetrydeck.com/survey/). Through these we provide information about [majorMinorVersions](https://telemetrydeck.com/survey/apple/iOS/minorSystemVersions/) and [majorVersions](https://telemetrydeck.com/survey/apple/iOS/majorSystemVersions/) currently used according to our data set as well as device related information regarding [iPhone models](https://telemetrydeck.com/survey/apple/iPhone/models/) for example.

diff --git a/articles/documentation.md → docs/articles/documentation.md b/articles/documentation.md → docs/articles/documentation.md
@@ -79,16 +79,14 @@ Organizational tags like `docs` and `guides` are automatically applied. Use the
 - The experience level of the reader (`beginner`, `intermediate`, `advanced`)
 - The type of query (`filter`, `cohorts`, etc.)
 
-{% noteinfo "You don't need to add 'docs' and 'articles' as tags" %}
+!!! warning "You don't need to add 'docs' and 'articles' as tags"
 
-All markdown files in the `docs` repository automatically get the `docs` tag applied to them (by `docs.11tydata.js`). In addition, the respective directories apply their own tags as well:
+    All markdown files in the `docs` repository automatically get the `docs` tag applied to them (by `docs.11tydata.js`). In addition, the respective directories apply their own tags as well:
 
-- Files in the `intro` directory get the `intro` tag applied.
-- Files in the `guides` directory get the `guides` tag applied.
-- Files in the `articles` directory get the `articles` tag applied.
-- Files in the `api` directory get the `api` tag applied.
-
-{% endnoteinfo %}
+    - Files in the `intro` directory get the `intro` tag applied.
+    - Files in the `guides` directory get the `guides` tag applied.
+    - Files in the `articles` directory get the `articles` tag applied.
+    - Files in the `api` directory get the `api` tag applied.
 
 ### Order
 
@@ -188,25 +186,25 @@ and [links](https://www.markdownguide.org/basic-syntax/#link).
 
 ## Images
 
-To display an image in a docs article, add it to the `images` directory. You can then link it using regular markdown image syntax, adding `/docs/images/` before the images' name.
+To display an image in a docs article, add it to the `assets` directory. You can then link it using regular markdown image syntax, adding `/assets/` before the image's name.
 
-Example: You just added the file `privacy-overview.png` to the `images` folder. You can now display that image like so:
+Example: You just added the file `privacy-overview.png` to the `assets` folder. You can now display that image like so:
 
 ```markdown
-![A screenshot of Apple's Privacy Overview](/docs/images/privacy-overview.png)
+![A screenshot of Apple's Privacy Overview](/assets/privacy-overview.png)
 ```
 
-The first part is the image's alt text. The second part is the path (`/docs/images/`) and the image file name `privacy-overview.png`.
+The first part is the image's alt text. The second part is the path (`/assets/`) and the image file name `privacy-overview.png`.
 
 Here's what it looks like:
 
-![A screenshot of Apple's Privacy Overview](/docs/images/privacy-overview.png)
+![A screenshot of Apple's Privacy Overview](/assets/privacy-overview.png)
 
 {% notewarning "Image File Locations" %}
 
-Image files need to live in the `images` directory at the root of the `docs` repository. Image files that are elsewhere in the file hierarchy will be ignored.
+Image files need to live in the `assets` directory inside `docs/`. Image files elsewhere in the file hierarchy will be ignored.
 
-You need to prefix `/docs/images/` to the path when linking to the image, since the Docs repository lives inside a `/docs` folder on deployment.
+Prefix `/assets/` to the path when linking to the image — the path is resolved against the docs site root.
 {% endnotewarning %}
 
 ## Code Blocks

diff --git a/articles/duration-signals.md → docs/articles/duration-signals.md b/articles/duration-signals.md → docs/articles/duration-signals.md
@@ -84,11 +84,11 @@ The histogram aggregation type is perfect for visualizing the distribution of du
 
 1. Create a new insight of type "Advanced Query", then open the "JSON Editor":
 
-    ![A screenshot of the Query Creator dialog](/docs/images/duration-signal-01.png)
+    ![A screenshot of the Query Creator dialog](/assets/duration-signal-01.png)
 
 2. Copy & paste the following histogram aggregation query and adjust `<YOUR_SIGNAL_NAME>` to your needs:
 
-    ![A screenshot of the JSON Editor text field](/docs/images/duration-signal-02.png)
+    ![A screenshot of the JSON Editor text field](/assets/duration-signal-02.png)
 
     ```json
     {
@@ -125,7 +125,7 @@ The histogram aggregation type is perfect for visualizing the distribution of du
 
 3. Set the chart type to be a bar chart in the UI via the insight's top right segmented control:
 
-    ![A screenshot of the insight set to be a bar chart](/docs/images/duration-signal-03.png)
+    ![A screenshot of the insight set to be a bar chart](/assets/duration-signal-03.png)
 
 4. You might also want to adjust the `splitPoints` array based on the expected duration of your activity, for example:
     - **Short interactions** (button clicks): `[0, 0.05, 0.1, 0.15, 0.2, 0.3, 0.5, 1, 2, 5]`

diff --git a/articles/grand-rename.md → docs/articles/grand-rename.md b/articles/grand-rename.md → docs/articles/grand-rename.md
diff --git a/articles/hosting-solutions.md → docs/articles/hosting-solutions.md b/articles/hosting-solutions.md → docs/articles/hosting-solutions.md