percona · ademidoff · Jan 7, 2025 · Dec 20, 2024 · Dec 20, 2024 · Dec 20, 2024
@@ -14,20 +14,26 @@ doc-check-images:   ## Check if all images are used in documentation
 doc-remove-images:  ## Remove unused images from documentation
 	@ACTION=remove $(DIR)/resources/bin/check-images.sh
 
-doc-build:          ## Build documentation
+doc-build:          ## Build documentation (used in CI)
 	# This command is used to build and deploy a preview to onrender.com
 	# Preview URL: https://pmm-doc.onrender.com
 
 	mkdocs build -f $(DIR)/mkdocs.yml
 
-doc-build-pdf:			## Build documentation in PDF format
+doc-build-pdf:      ## Build documentation in PDF format
+	docker run --rm --platform=linux/amd64 -v $(DIR):/docs -w /build perconalab/pmm-doc-md:latest \
+		bash -c " \
+			cp -r /docs/* /build/ && \
+			git init && \
+			git config user.email '[email protected]' && \
+			git add --all && \
+			git commit -am 'Initial commit' > /dev/null && \
+			mkdocs build -f mkdocs-pdf.yml && \
+			cp /build/site/pdf/*.pdf /docs/ \
+		"
+
+doc-build-image:    ## Build perconalab/pmm-doc-md:latest image
 	# @docker buildx build --platform=linux/amd64 --progress=plain -t perconalab/pmm-doc-md:latest -f documentation/resources/Dockerfile.build .
-	docker run --rm --platform=linux/amd64 -v $(DIR):/docs -w /build -e ENABLE_PDF_EXPORT=1 perconalab/pmm-doc-md:latest \
-		bash -c "cp -r /docs/* /build/ && \
-		ls -la /build && \
-		git init && \
-		git config user.email '[email protected]' && \
-		git add --all && \
-		git commit -am 'Initial commit' && \
-		mkdocs build -f mkdocs-pdf.yml && \
-		cp /build/site/pdf/*.pdf /docs/"
+
+doc-view-icons:     ## View icons that can be used in documentation
+	@open https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search
@@ -125,8 +125,19 @@ In some places, we have used variables themselves to solve the problem. In other
 
 ## Icons
 
+Currently, we use three different sets of icons:
+
+- Native Mkdocs Material icons and emojis
+- Iconscount Unicons
+- FontAwesome Icons
+
+The preference should be given to Mkdocs Material icons, since they were initially designed for `mkdocs` project and work very well with it. In rare cases, when an icon cannot be found in Mkdocs Material, you can find a suitable one on Iconscout. FontAwesome icons do not play well with Mkdocs, so use them with caution and don't forget to apply additional CSS styles in case they don't render well in PDF.
+
+Ideally, we should migrate to using just the two first sets.
+
 Use HTML for icons:
 
+- For Material Theme Icons (`:` prefix and suffix), go to <https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/>, find an icon, select it and copy the code here.
 - For PMM UI (Grafana) icons (`uil-` prefix), go to <https://iconscout.com/unicons/explore/line>, find an icon, select 'Font' and copy the code here.
 - For Font Awesome (`fa-` prefix), go to <https://fontawesome.com/icons>, find an icon, copy the code.
 

@@ -1,8 +1,26 @@
 @media print {
-    /* Adjusts positioning of admonition icon */
-    .md-typeset :is(.admonition-title,summary):before {
-      top: 0.6rem;
-      left: 0.6rem;
-    }
+  /* Adjusts positioning of admonition icon */
+  .md-typeset :is(.admonition-title,summary):before {
+    top: 0.6rem;
+    left: 0.6rem;
   }
+
+  .no-pdf {
+    display: none !important;
+  }
+
+  .power-number+ol>li::before,
+  .power-number+ol ol>li::before {
+    background-color: var(--md-default-bg-color);
+    color: var(--md-typeset-color);
+    border-radius: 0;
+    width: 1.5em;
+    margin-left: -1.7em;
+    opacity: 1;
+  }
+
+  .tabbed-content {
+    display: contents;
+  }
+}
 
@@ -1,6 +1,8 @@
 # About PMM
 
-<i info>:material-information: Info:</i> This is the documentation for the latest release, **PMM {{release}}** Beta. See the [Release Notes](release-notes/3.0.0_Beta.md) for details.
+!!! info ""
+
+    This is the documentation for the latest release, **PMM {{release}}** Beta. See the [Release Notes](release-notes/3.0.0_Beta.md) for details.
 
 Percona Monitoring and Management (PMM) is an open source database observability, monitoring, and management tool for use with MySQL, PostgreSQL, MongoDB, and the servers on which they run. It enables you to view node- to single-query performance metrics for all of your databases in a single place. 
 
@@ -14,7 +16,7 @@ Percona Monitoring and Management (PMM) is an open source database observability
 
     Would you like to see a preview of our Home page? Take a look at our free, live [demo](https://pmmdemo.percona.com/).
 
-<div data-grid markdown><div data-banner markdown>
+<div class="no-pdf" data-grid markdown><div data-banner markdown>
 
 ## :material-telescope: Discover { .title }
 
@@ -33,7 +35,7 @@ Ready to dive into PMM? Follow our simple, step-by-step installation instruction
 
 </div><div data-banner markdown>
 
-## :fontawesome-solid-gear: Configure { .title }
+## :material-cog: Configure { .title }
 
 Are you ready to begin configuring PMM  but need help figuring out how to begin? Let's dive in together.
 
@@ -49,6 +51,3 @@ Looking for reliable and easy-to-use resources to tackle your daily challenges w
 
 </div>
 </div>
-
-
-
@@ -15,35 +15,40 @@ Install and run at least one PMM Server. Choose from the following options:
      PMM Server is not currently available as a native ARM64 build. For ARM-based systems, consider using the Docker or Podman installation methods, which can run x86_64 images via emulation on ARM platforms.
 
 
-| Use | <i class="uil uil-thumbs-up"></i> **Benefits** | <i class="uil uil-thumbs-down"></i> **Drawbacks**|
+| Use | :material-thumb-up: **Benefits** | :material-thumb-down: **Drawbacks**|
 |---|---|---
 | [Docker] | 1. Quick<br>2. Simple<br> 3. Rootless |  Additional network configuration required.
-| [Podman] | 1. Quick<br>2. Simple<br>3. Rootless |Podman installation required.
-| [Helm] (Technical Preview) | 1. Quick<br>2. Simple<br>3. Cloud <br> 4. Rootless| Requires running Kubernetes cluster.
+| [Podman] | 1. Quick<br>2. Simple<br>3. Rootless | Podman installation required.
+| [Helm] (Technical Preview) | 1. Quick<br>2. Simple<br>3. Cloud-compatible <br> 4. Rootless| Requires running a Kubernetes cluster.
 | [Virtual appliance]  | 1. Easily import into Hypervisor of your choice <br> 2. Rootless| More system resources compared to Docker footprint.
-| [Amazon AWS] | 1. Wizard-driven install. <br>  2. Rootless| Non-free solution (infrastructure costs).
+| [Amazon AWS] | 1. Wizard-driven install. <br>  2. Rootless| Paid, incurs infrastructure costs.
 
 ## Install PMM Client
 
 Install and run PMM Client on every node where there is a service you want to monitor. PMM Client now supports both x86_64 and ARM64 architectures.
 
 The installation choices are:
 
-    === "With Docker" 
+=== "With Docker"
 
-     [Docker installation](client/index.md#docker) simplifies deployment across different architectures and automatically selects the appropriate image for your architecture (x86_64 or ARM64).=p][\;]
+    - [Docker installation](client/index.md#docker) simplifies deployment across different architectures and automatically selects the appropriate image for your architecture (x86_64 or ARM64).
 
-    === "Native installation"      
+=== "With package manager"
 
     - [Linux package](client/index.md#package-manager). Use `apt`, `apt-get`, `dnf`, `yum`. The package manager automatically selects the correct version for your architecture.
 
-    - [Binary package](client/index.md#binary-packa): Download the appropriate `.tar.gz` file for your architecture (x86_64 or ARM64).
+=== "With binary package"
+
+    - [Binary package](client/index.md#binary-package): Download the appropriate `.tar.gz` file for your architecture (x86_64 or ARM64).
+
 
 !!! hint alert "Tips"
     Both binary installation and Docker containers can be run without root permissions. When installing on ARM-based systems, ensure you're using ARM64-compatible versions. Performance may vary between architectures.
 
 ## Add services
+
 On each PMM Client instance, configure the nodes and services you want to monitor. 
+
 ??? info "Which services you can monitor?"
 
     - [MySQL] (and variants: Percona Server for MySQL, Percona XtraDB Cluster, MariaDB);

@@ -166,7 +166,8 @@ On the other hand, the manual method offers a simpler setup with complete contro
     4. Go to `https://localhost:8443` to access the PMM user interface in a web browser. If you are accessing the host remotely, replace `localhost` with the IP or server name of the host.
 
     For information on manually upgrading, see [Upgrade PMM Server using Podman](../../../../pmm-upgrade/upgrade_podman.md).
-=======
+
+
 ## Run as non-privileged user to start PMM
 
 ??? info "Summary"
@@ -288,4 +289,4 @@ To run Podman as a non-privileged user:
 sleep 80
 timeout 60 podman wait --condition=running pmm-server
 ```
-</div>
+</div>
@@ -9,15 +9,15 @@ For PMM to work correctly, your system's firewall should allow TCP traffic on th
 Ports to expose:
 
 | PMM component | TCP port      | Direction     | Description
-|---------------|---------------|---------------|-----------------------------------------------------------------------------------------------------------------
+|---------------|---------------|---------------|------------------------------------------------------------------------------------------
 | PMM Server    |   80          | both          | HTTP server, used for gRPC over HTTP and web interface (**insecure**, use with caution).
 | PMM Server    |  443          | both          | HTTPS server, used for gRPC over HTTPS and web interface (secure, use of SSL certificates is highly encouraged).
 
 Other ports:
 
 | PMM component | TCP port      | Direction     | Description
-|---------------|---------------|---------------|---------------------------------------------------------------
-| PMM Server    | 7771          | both          | gRPC, used for communication between `pmm-agent`, `pmm-admin`.
+|---------------|---------------|---------------|-----------------------------------------------------------------
+| PMM Server    | 7771          | both          | gRPC, used for communication between `pmm-agent` and `pmm-admin`.
 | PMM Server    | 7772          | out           | HTTP1 server, used for older links like `logs.zip`.
 | PMM Server    | 7773          | out           | Debugging.
 | `pmm-agent`   | 7777          | out           | Default `pmm-agent` listen port.
@@ -28,7 +28,7 @@ Other ports:
     Depending on your architecture other ports may also need to be exposed.
 
     - For `pmm-agent`, the default listen port is 7777.
-    - The default port range for `pmm-agent` is large by default to accommodate any architecture size but it can be modified using the `--ports-min` and `--ports-max` flags, or modifying the configuration file. In network constraint environments, the range can be reduced to a minimum by allocating at least one port per agent monitored. Learn more about available settings for `pmm-agent` in [Percona PMM-Agent documentation](https://docs.percona.com/percona-monitoring-and-management/details/commands/pmm-agent.html).
+    - The default port range for `pmm-agent` is large by default to accommodate any architecture size but it can be modified using the `--ports-min` and `--ports-max` flags, or by changing the configuration file. In network constraint environments, the range can be reduced to a minimum by allocating at least one port per agent monitored. Learn more about available settings for `pmm-agent` in [Percona PMM-Agent documentation](https://docs.percona.com/percona-monitoring-and-management/3/use/commands/pmm-agent.html).
 
 ## Network configuration for locked-down environments
 For computers in a locked-down corporate environment without direct access to the Internet, make sure to enable access to Percona Platform services following the instructions in the [Percona Platform documentation](https://docs.percona.com/percona-platform/network.html).
@@ -29,12 +29,12 @@ Delete the search text and press Enter to see the full list again.
 
 - The first column is the object’s identifier. For **Query**, it is the query’s [Fingerprint](../../../reference/glossary.md#fingerprint).
 - The second column is the **Main metric**, containing a reduced graphical representation of the metric over time, called a **sparkline**, and a horizontal meter, filled to reflect a percentage of the total value.
-- Additional values are revealed as mouse-over tool-tips.
+- Additional values are revealed as mouse-over tooltips.
 
-## Tool-tips
+## Tooltips
 
-- For the **Query** dimension, hovering over the information icon <i class="fa fa-info-circle"></i> reveals the query ID and its example.
-- Hovering on a column header reveals an informative tool-tip for that column.
+- For the **Query** dimension, hovering over the information icon :material-information: reveals the query ID and its example.
+- Hovering on a column header reveals an informative tooltip for that column.
 - Hovering on the main metric sparkline highlights the data point and a tooltip shows the data value under the cursor.
 
 ![!image](../../../images/PMM_Query_Analytics_Main_Metric_Sparkline.jpg)
@@ -68,4 +68,4 @@ Delete the search text and press Enter to see the full list again.
 
     ![!image](../../../images/PMM_Query_Analytics_Devices_Pagination.jpg)
 
-- Queries are grouped into pages of 25, 50 or 100 items.
+- Queries are grouped into pages of 25, 50 or 100 items.
@@ -57,11 +57,11 @@ theme:
 extra_css:
   - https://unicons.iconscout.com/release/v3.0.3/css/line.css
   - https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.4.0/css/font-awesome.min.css
-  - css/extra.css
   - css/nocopy.css
   - css/design.css
   - css/osano.css
   - css/pmm.css
+  - css/extra.css
 
 extra_javascript:
   - js/promptremover.js
@@ -78,7 +78,7 @@ markdown_extensions:
   meta: {}
   md_in_html: {}
   smarty:
-      smart_angled_quotes: true
+    smart_angled_quotes: true
   pymdownx.details: {}
   pymdownx.mark: {}
   pymdownx.smartsymbols: {}

@@ -1,5 +1,5 @@
 # MkDocs configuration for PDF output
-# Usage: ENABLE_PDF_EXPORT=1 mkdocs build -f mkdocs-pdf.yml
+# Usage: mkdocs build -f mkdocs-pdf.yml
 INHERIT: mkdocs-base.yml
 
 plugins:
@@ -9,8 +9,7 @@ plugins:
   with-pdf:
     output_path: "pdf/PerconaMonitoringAndManagement-3.0.0-beta.pdf"
     cover_title: "Percona Monitoring and Management Documentation"
-    cover_subtitle: 3.0.0 (December 11, 2024)
+    cover_subtitle: 3.0.0 (December 13, 2024)
     author: "Percona Technical Documentation Team"
     cover_logo: docs/images/Percona_Logo_Color.png
     custom_template_path: resources/templates
-    enabled_if_env: ENABLE_PDF_EXPORT
@@ -1,4 +1,4 @@
-<div data-banner markdown><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 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"/><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 offset="1" stop-color="#F0D136"/></linearGradient></defs></svg>
+<div class="no-pdf" data-banner markdown><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 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"/><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 offset="1" stop-color="#F0D136"/></linearGradient></defs></svg>
 
 ## Get expert help { .title }