PMM-3 Fix pdf rendering (#3409)

* PMM-7 Fix PDF rendering (phase I)

* chore: trigger the build

* PMM-7 Apply more css fixes for PDF

* PMM-7 Add doc-build-image make target

* PMM-7 Apply different fixes

* PMM-7 Remove redundant markup

* PMM-7 Update the Makefile

* PMM-7 Provide comments in css overrides for PDF

* PMM-7 Add a local build preview

documentation/Makefile

@@ -14,20 +14,36 @@ 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-build-preview:  ## Build documentation and preview at http://localhost:8000
+	docker run --rm --platform=linux/amd64 -p 8000:8000 -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 serve -f mkdocs.yml --dev-addr=0.0.0.0:8000 \
+		"
+doc-search-icons:     ## Search for icons that can be used in documentation
+	@open https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search

documentation/WRITERS-NOTES.md

@@ -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.
 

documentation/docs/css/extra.css

@@ -1,8 +1,28 @@
 @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;
   }
+
+  /* Do not render html tags with this class in PDF */
+  .no-pdf {
+    display: none !important;
+  }
+
+  /* Modify rendering of numbered lists in PDF */
+  .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;
+  }
+}
 

documentation/docs/index.md

@@ -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>
-
-
-

documentation/docs/install-pmm/index.md

@@ -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);

documentation/docs/install-pmm/install-pmm-server/baremetal/podman/index.md

@@ -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>

documentation/docs/install-pmm/plan-pmm-installation/network_and_firewall.md

@@ -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).

documentation/docs/use/qan/panels/overview.md

@@ -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.

documentation/mkdocs-base.yml

@@ -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: {}

documentation/mkdocs-pdf.yml

@@ -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