V3 doc prod

documentation/docs/css/extra.css

@@ -27,33 +27,21 @@
     line-height: 1.6;
 }
 
-.md-content__button.md-icon {
-  color: #f56a37 !important;
+.edit-page-link {
+  white-space: nowrap;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5em;
+  font-size: 1.2rem;
+  font-weight: normal;
+  color: var(--md-typeset-a-color);
+  text-decoration: underline;
 }
 
-/* Optional: hover effect */
-.md-content__button.md-icon:hover {
-  color: #dc3f00 !important;
-}
-
-.md-content__button.md-icon[href*="/edit/"] {
-  display: inline-flex;          /* make the button a flex container */
-  flex-direction: column;        /* stack children vertically */
-  align-items: center;           /* center them horizontally */
-  margin-top: -4px;
-}
-
-.md-content__button.md-icon[href*="/edit/"] svg {
-  width: 32px;
-  height: 32px;
-}
-
-.md-content__button.md-icon[href*="/edit/"]::after {
-  content: "Improve this page";
-  margin-top: 2px;
-  font-size: 0.7rem;
-  text-align: center;
-  display: block;
-  width: 100%;
+.edit-page-icon svg {
+  width: 1.40em;
+  height: 1.40em;
+  fill: currentColor;
+  vertical-align: middle;
 }
 

documentation/docs/install-pmm/install-pmm-server/deployment-options/helm/index.md

@@ -147,24 +147,25 @@ Create the required Kubernetes secret and deploy PMM Server using Helm:
 
         ```bash
         # If using ClusterIP (default)
-        kubectl port-forward svc/pmm-service 443:443
+        kubectl port-forward svc/monitoring-service 443:443
+
 
         # If using NodePort
-        kubectl get svc pmm-service -o jsonpath='{.spec.ports[0].nodePort}'
+        kubectl get svc monitoring-service -o jsonpath='{.spec.ports[0].nodePort}'
         ```
 
     === "On OpenShift"
         OpenShift offers native routing capabilities through its Route resource, which provides external access with built-in load balancing and SSL termination:
 
         ```bash
         # Create a Route to expose PMM
-        oc expose svc/pmm-service --port=443
+        oc expose svc/monitoring-service --port=443
 
         # Get the Route URL
-        oc get route pmm-service -o jsonpath='{.spec.host}'
-        
+        oc get route monitoring-service -o jsonpath='{.spec.host}'
+
         # Or use port-forwarding for testing
-        oc port-forward svc/pmm-service 443:443
+        oc port-forward svc/monitoring-service 443:443
         ```
 
 ### Configure PMM Server

documentation/docs/reference/faq.md

@@ -2,8 +2,8 @@
 
 ## How can I contact the developers?
 
-- [Community forum](https://www.percona.com/forums/questions-discussions/percona-monitoring-and-management).
-- [PMM project in JIRA](https://jira.percona.com/projects/PMM).
+- [Community forum](https://forums.percona.com/c/percona-monitoring-and-management-pmm)
+- [PMM project in JIRA](https://perconadev.atlassian.net/jira/software/c/projects/PMM/issues)
 
 ## What are the minimum system requirements?
 
@@ -13,18 +13,29 @@ See our detailed guides:
 - [Setting up PMM Server](../install-pmm/install-pmm-server/index.md) for server installation  
 - [Setting up PMM Client](../install-pmm/install-pmm-client/index.md) for client setup
 
-Quick reference for typical deployment (up to 30 nodes):
-- **Server**:
-    - CPU: 4 cores (must support SSE4.2)
-    - Memory: 8 GB
-    - Storage: 100 GB (approximately 1 GB per node per week)
-- **Client**:
-    - Storage: 100 MB
-    - Supports x86_64 and ARM64 architectures
+## What are the minimum system requirements?
+
+See our detailed guides:
+
+- [PMM hardware and system requirements](../install-pmm/plan-pmm-installation/hardware_and_system.md) for complete specifications
+- [Setting up PMM Server](../install-pmm/install-pmm-server/index.md) for server installation  
+- [Setting up PMM Client](../install-pmm/install-pmm-client/index.md) for client setup
+
+### Quick reference: Typical deployment (up to 30 nodes)
+
+**Server requirements:**
+
+- CPU: 4 cores (must support SSE4.2)
+- Memory: 8 GB
+- Storage: 100 GB (~1 GB per node per week)
+
+**Client requirements:**
 
-!!! note alert alert-info "Note"
-    For larger deployments (200+ nodes) or longer retention periods, see our [Hardware and system requirements](../install-pmm/plan-pmm-installation/hardware_and_system.md) for detailed sizing recommendations.
+- Storage: 100 MB
+- Architecture: x86_64 and ARM64 supported
 
+For larger deployments (200+ nodes) or extended retention, see [Hardware and system requirements](../install-pmm/plan-pmm-installation/hardware_and_system.md) for detailed sizing guidance.
+
 ## How can I upgrade from version 2?
 
 PMM 3 introduces significant architectural changes that require gradual transition from PMM 2. For detailed instructions, see [Upgrade from PMM2](../pmm-upgrade/migrating_from_pmm_2.md).
@@ -39,23 +50,20 @@ If you encounter errors such as `ERROR: Unsupported distribution` when running t
 
 ## Retention
 
-To control data retention, go to **PMM Configuration > Settings > Advanced Settings > Data retention** to adjust the value in days.
-
-!!! seealso alert alert-info "See also"
-    [Configure data retention](../configure-pmm/advanced_settings.md#data-retention)
+To control data retention, go to **PMM Configuration > Settings > Advanced Settings > Data retention** to adjust the value in days. See also [Configure data retention](../configure-pmm/advanced_settings.md#data-retention).
 
 ## How are PMM Server logs rotated?
 
-PMM Server embeds multiple components, like Victoria Metrics, Query Analytics, Grafana, `managed`, PostgreSQL, ClickHouse, etc. (components). All PMM Server component logs are rotated by `supervisord`. The components' log rotation settings are stored in `*.ini` files within the `/etc/supervisord.d` directory. Those settings define both the maximum size of a log file and the number of log files to keep. The log rotation takes place once the log file reaches its maximum size.
+PMM Server embeds multiple components, like Victoria Metrics, Query Analytics, Grafana, `managed`, PostgreSQL, ClickHouse, etc. (components). All PMM Server component logs are rotated by `supervisord`. 
+
+The components' log rotation settings are stored in `*.ini` files within the `/etc/supervisord.d` directory. Those settings define both the maximum size of a log file and the number of log files to keep. The log rotation takes place once the log file reaches its maximum size.
 
 ## What privileges are required to monitor a MySQL instance?
 
 ```sql
 SELECT, PROCESS, SUPER, REPLICATION CLIENT, RELOAD
 ```
-
-!!! seealso alert alert-info "See also"
-    [Setting Up/Client/MySQL](../install-pmm/install-pmm-client/connect-database/mysql/mysql.md#create-a-database-account-for-pmm).
+See also [Connect MySQL database](../install-pmm/install-pmm-client/connect-database/mysql/mysql.md#create-a-database-account-for-pmm).
 
 ## Can I monitor multiple service instances?
 
@@ -72,8 +80,7 @@ pmm-admin add mysql --username root --password root instance-01 127.0.0.1:3001
 pmm-admin add mysql --username root --password root instance-02 127.0.0.1:3002
 ```
 
-!!! seealso alert alert-info "See also"
-    [`pmm-admin add mysql`](../use/commands/pmm-admin.md#database-commands)
+See also [`pmm-admin add mysql`](../use/commands/pmm-admin.md#database-commands).
 
 ## Can I rename instances?
 
@@ -100,8 +107,7 @@ The default values (in seconds):
 | Frequent          | 30   | 5      | 1    |
 | Custom (defaults) | 60   | 10     | 5    |
 
-!!! seealso alert alert-info "See also"
-    [Metrics resolution](../configure-pmm/metrics_res.md)
+See also [Metrics resolution](../configure-pmm/metrics_res.md).
 
 ## How do I set up Alerting?
 
@@ -111,8 +117,7 @@ For this, you must configure alerting rules that define conditions under which a
 
 Percona templated alerts enable you to create alerts based on built-in or custom templates to simplify the alert setup process. Grafana managed alerts allows attaching rules to your dashboard panel and enables you to create more sophisticated alerting rules. In addition, it can be easier to manage installations with a large number of hosts. This additional flexibility comes at the expense of simplicity.
 
-!!! seealso alert alert-info "See also"
-    [Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/)
+See also [Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/).
 
 ## How do I use a custom Prometheus configuration file?
 
@@ -124,9 +129,7 @@ From version 2.4.0, when `pmm-managed` starts the Prometheus file generation pro
 
 The `prometheus.yml` file can be regenerated by restarting the PMM Server container, or by using the `SetSettings` API call with an empty body.
 
-!!! seealso alert alert-info "See also"
-    - [API](../api/index.md)
-    - [Percona blog: Extending PMM’s Prometheus Configuration](https://www.percona.com/blog/2020/03/23/extending-pmm-prometheus-configuration/)
+See also [API](../api/index.md) and [Percona blog: Extending PMM’s Prometheus configuration](https://www.percona.com/blog/2020/03/23/extending-pmm-prometheus-configuration/). 
 
 ## How to troubleshoot an upgrade?
 
@@ -139,8 +142,7 @@ See [Troubleshoot update](../troubleshoot/upgrade_issues.md).
 
 PMM protects an exporter's output from unauthorized access by adding an authorization layer. To access an exporter, you can use `pmm` as a user name and the Agent ID as a password. You can find the Agent ID corresponding to a given exporter by running `pmm-admin list`.
 
-!!! seealso alert alert-info "See also"
-    [`pmm-admin list`](../use/commands/pmm-admin.md#information-commands)
+See also [`pmm-admin list`](../use/commands/pmm-admin.md#information-commands).
 
 ## How to provision PMM Server with non-default admin password?
 
@@ -159,18 +161,18 @@ Once PMM has started, you can use either of the following to change the password
 
 - a helper script `change-admin-password`:
 
-```sh
-docker exec -t pmm-server change-admin-password your_secure_password
-```
+    ```sh
+    docker exec -t pmm-server change-admin-password your_secure_password
+    ```
 
 - or a code snippet:
 
-```sh
-PMM_PASSWORD="mypassword"
-echo "Waiting for PMM to initialize to set password..."
-until [ $(docker inspect -f {% raw %}'{{.State.Health.Status}}'{% endraw %} pmm-server) = "healthy" ]; do sleep 1; done
-docker exec -t pmm-server bash -c  "grafana cli --homepath /usr/share/grafana --config=/etc/grafana/grafana.ini admin reset-admin-password $PMM_PASSWORD"
-```
+    ```sh
+    PMM_PASSWORD="mypassword"
+    echo "Waiting for PMM to initialize to set password..."
+    until [ $(docker inspect -f {% raw %}'{{.State.Health.Status}}'{% endraw %} pmm-server) = "healthy" ]; do sleep 1; done
+    docker exec -t pmm-server bash -c  "grafana cli --homepath /usr/share/grafana --config=/etc/grafana/grafana.ini admin reset-admin-password $PMM_PASSWORD"
+    ```
 
 ## How to use a non-default listen-port for pmm-admin?
 
@@ -196,17 +198,21 @@ change-admin-password <new_password>
 
 Read our [Privacy Policy](https://www.percona.com/privacy-policy) to learn how PMM manages personal and confidential data. More technical details can be found in [Data handling in PMM](personal_data_handling.md).
 
-## Why am I getting a "User already exists" error when logging back into PMM?
+## Why am I getting a "User already exists" error when logging into PMM?
+
+Starting with PMM 2.38, we implemented a security fix for [CVE-2023-3128](https://grafana.com/blog/2023/06/22/grafana-security-release-for-cve-2023-3128/). PMM now requires a unique user ID from your identity provider during authentication. If your provider doesn't supply this identifier, you'll see a "User already exists" error on subsequent login attempts.
+
+### Solution
 
-Following [CVE fix 2023-3128](https://grafana.com/blog/2023/06/22/grafana-security-release-for-cve-2023-3128/) in the 2.38 release, PMM increases security by only allowing authentications based on the unique user ID provided by the identity provider.
+Use a Percona Account to log into PMM. This is the recommended and most secure authentication method, as Percona Accounts fully support unique user IDs.
 
-If you are trying to log into PMM via a third-party authentication provider which doesn't support a unique ID field, PMM will show this error on second and subsequent authentications.
+### Workaround
 
-**Solution**: we recommend logging into PMM using a Percona Account, as this is a highly secure authentication method.
-**Workaround**: if you need to log into PMM via a third-party authentication provider which doesn’t support a unique ID field, you can use the following workaround to log into PMM:
+If you must use a third-party identity provider without unique ID support, set this environment variable on your PMM container:
 
-  - pass the `GF_AUTH_OAUTH_ALLOW_INSECURE_EMAIL_LOOKUP=1` environment variable to the PMM container **OR**
-  - set the `oauth_allow_insecure_email_lookup` config key in the auth section of the `grafana.ini` file. Keep in mind that any changes you make to this file are lost when upgrading PMM, so make sure to manually update this file after each upgrade.
+```sh
+GF_AUTH_OAUTH_ALLOW_INSECURE_EMAIL_LOOKUP=1
+```
 
-!!! caution alert alert-warning "Important"
-    We do not recommend using the above workaround for an extended period. Instead, ensure user uniqueness across multiple identity providers, while also encouraging your identity provider to support a unique ID field, or choose a provider who does.
+!!! caution
+    This workaround reduces security and should only be temporary. We recommend either switching to a Percona Account or using an identity provider that supports unique user IDs. Ensure your provider implements unique ID fields to maintain long-term security.

documentation/docs/release-notes/3.4.0.md

@@ -92,7 +92,9 @@ For detailed steps, see [Migrating PMM from VMware to alternative platforms](../
 
 ## Improvements
 
-- [PMM-14194](https://perconadev.atlassian.net/browse/PMM-14194): Custom filter groups in Query Analytics (QAN) now correctly distinguish between intentional comments and quoted strings containing comment-like characters. Previously, queries with values like `street = '123 Main St # app=something'` would incorrectly generate unwanted custom filters. Now, only genuine SQL comments such as `-- app='web', team='backend'` create filter options in the **PMM Query Analytics** dashboard sidebar. This means that you get cleaner query categorization when [comment parsing](../use/qan/panels/filters.md#custom-filter-groups) is enabled.
+- [PMM-14194](https://perconadev.atlassian.net/browse/PMM-14194): Custom filter groups in Query Analytics (QAN) now correctly distinguish between intentional comments and quoted strings containing comment-like characters. Previously, queries with values like `street = '123 Main St # app=something'` would incorrectly generate unwanted custom filters. 
+
+    Now, only genuine SQL comments such as `-- app='web', team='backend'` create filter options in the **PMM Query Analytics** dashboard sidebar. This means that you get cleaner query categorization when [comment parsing](../use/qan/panels/filters.md#custom-filter-groups) is enabled.
 
 - [PMM-14048](https://perconadev.atlassian.net/browse/PMM-14048): Reorganized MongoDB dashboards for better usability. The **MongoDB PBM Details** and **PBM Backup Details** dashboards are now available directly from the main navigation for easier access, while the **MongoDB InMemory Details** and **MongoDB WiredTiger Details** dashboards are now relocated to **Other Dashboards**.
 

documentation/mkdocs-base.yml

@@ -47,8 +47,8 @@ theme:
     - content.tabs.link
     - content.code.copy
     - navigation.tracking
-    - content.action.edit
-#    - content.action.view
+#    - content.action.edit
+    - content.action.view
 
 extra_css:
   - https://unicons.iconscout.com/release/v4.0.8/css/line.css

documentation/mkdocs.yml

@@ -20,4 +20,4 @@ extra:
           name: This page could be improved
           data: 0
           note: >- 
-            Thanks for your feedback! Want to improve this page? Click the <strong>Improve this page</strong> button above to submit a pull request!
+            Thanks for your feedback! Want to improve this page? Click  <strong>Edit this page on GitHub</strong> above to submit a pull request.

documentation/overrides/main.html

@@ -46,11 +46,14 @@
                 <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" {{ hidden }}>
                   <div class="md-sidebar__scrollwrap">
                     <div class="md-sidebar__inner">
-                      {% include "partials/toc.html" %}
+                      {% include "partials/edit.html" %}
                     </div>
                     <div class="md-sidebar__inner">
                       {% include "partials/banner.html" %}
                     </div>
+                    <div class="md-sidebar__inner">
+                      {% include "partials/toc.html" %}
+                    </div>
                   </div>
                 </div>
               {% endif %}

documentation/overrides/partials/banner.html

@@ -1,6 +1,6 @@
 <div data-banner="data-banner">
     <p><svg style="display:block;margin:-1em 0 0.75em" width="78" height="69" viewBox="0 0 78 69" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M56.7281 30.7666C62.6528 26.8938 64.5914 18.9942 61.0059 12.7854C59.2094 9.67113 56.3053 7.44082 52.8311 6.50951C49.6122 5.64535 46.2502 5.99872 43.2912 7.49366L39.251 0.5L30.8648 15.0245L11.4811 48.5937H67.021L56.7281 30.7666ZM51.881 10.0674C54.4064 10.7401 56.5079 12.3616 57.8168 14.6194C60.3895 19.0701 59.053 24.7153 54.8808 27.5665L45.1362 10.6905C47.2355 9.68104 49.6034 9.46087 51.881 10.0674ZM39.251 7.87125L60.6339 44.907H48.1228L32.9927 18.7102L39.2499 7.87235L39.251 7.87125ZM17.8682 44.907L30.8637 22.4035L43.8592 44.907H17.8682Z" fill="url(#paint0_linear_2899_1968)"></path><path style="fill:var(--md-typeset-color)" d="M4.981 64.943H3.157V68.207H.756V57.323H5.217C7.822 57.323 9.397 58.861 9.397 61.086V61.116C9.397 63.635 7.433 64.94 4.984 64.94L4.981 64.943V64.943ZM6.961 61.134C6.961 60.061 6.213 59.485 5.011 59.485H3.154V62.812H5.056C6.258 62.812 6.958 62.096 6.958 61.163V61.134H6.961ZM10.738 68.208V57.323H18.973V59.455H13.124V61.664H18.27V63.796H13.124V66.082H19.051V68.214H10.738V68.208 68.208ZM27.557 68.208 25.218 64.726H23.332V68.208H20.931V57.323H25.921C28.496 57.323 30.039 58.677 30.039 60.915V60.945C30.039 62.702 29.088 63.807 27.7 64.32L30.367 68.207H27.556L27.557 68.208ZM27.605 61.041C27.605 60.016 26.887 59.485 25.719 59.485H23.333V62.61H25.767C26.936 62.61 27.605 61.987 27.605 61.071V61.042 61.041ZM36.922 68.499C33.668 68.499 31.249 65.994 31.249 62.825V62.795C31.249 59.659 33.619 57.091 37.019 57.091 39.105 57.091 40.356 57.783 41.383 58.792L39.834 60.571C38.98 59.798 38.113 59.327 37.004 59.327 35.141 59.327 33.795 60.871 33.795 62.762V62.793C33.795 64.684 35.107 66.257 37.004 66.257 38.268 66.257 39.043 65.753 39.913 64.964L41.462 66.524C40.322 67.738 39.059 68.493 36.925 68.493L36.922 68.499ZM47.885 68.499C44.47 68.499 42.021 65.962 42.021 62.825V62.795C42.021 59.659 44.503 57.091 47.915 57.091 51.327 57.091 53.779 59.628 53.779 62.765V62.795C53.779 65.931 51.297 68.499 47.885 68.499ZM51.237 62.795C51.237 60.904 49.846 59.331 47.885 59.331 45.925 59.331 44.567 60.874 44.567 62.766V62.796C44.567 64.688 45.959 66.261 47.919 66.261 49.879 66.261 51.237 64.717 51.237 62.826V62.795 62.795ZM67.001 68.217 72.374 57.091 77.746 68.218H75.052L72.374 62.681 69.705 68.218H67.001V68.217ZM66.007 57.327V68.5L57.813 61.884V68.199H55.264V57.091L63.458 63.681V57.327H66.007Z"></path><defs><linearGradient id="paint0_linear_2899_1968" x1="18.1513" y1="44.7152" x2="61.4356" y2="20.9786" gradientUnits="userSpaceOnUse"><stop stop-color="#FC3519"></stop><stop offset="1" stop-color="#F0D136"></stop></linearGradient></defs></svg></p>
-    <p>For help, click the link below to get free database assistance or contact our experts for personalized support.</p>
+    <p>Get free database assistance or contact our experts for personalized support.</p>
 
     <div class="actions">
 

documentation/overrides/partials/edit.html

@@ -0,0 +1,11 @@
+<div data-banner="data-banner">
+  <div class="actions">
+    <a href="{{ page.edit_url }}" title="Edit this page on GitHub" class="edit-page-link">
+      <span class="edit-page-icon">
+        {% set icon = config.theme.icon.edit or "material/file-edit-outline" %}
+        {% include ".icons/" ~ icon ~ ".svg" %}
+      </span>
+      <span class="edit-page-text">Edit this page on GitHub</span>
+    </a>
+  </div>
+</div>