docs: Add validation Github Action for docs PRs

.github/workflows/ci.yml

@@ -5,6 +5,7 @@ on:
     branches:
       - main
   pull_request:
+    paths: ['!docs/**']
     branches:
       - main
 

.github/workflows/is-compatible.yml

@@ -1,5 +1,10 @@
 name: Latest Grafana API compatibility check
-on: [pull_request]
+
+on:
+  pull_request:
+    paths: ['!docs/**']
+    branches:
+      - main
 
 jobs:
   compatibilitycheck:

.github/workflows/publish-technical-documentation-next.yml

@@ -5,7 +5,7 @@ on:
     branches:
       - main
     paths:
-      - "docs/sources/**"
+      - 'docs/sources/**'
   workflow_dispatch:
 jobs:
   sync:
@@ -35,4 +35,3 @@ jobs:
           github_pat: grafanabot:${{ secrets.PUBLISH_TO_WEBSITE_TOKEN }}
           source_folder: docs/sources
           target_folder: content/docs/explore-profiles/next
-

.github/workflows/validate-documentation.yml

@@ -0,0 +1,15 @@
+name: Validate documentation
+
+on:
+  pull_request:
+    paths: ['docs/sources/**']
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build website
+        run: |
+          docker run -v ${PWD}/docs/sources:/hugo/content/docs/writers-toolkit -e HUGO_REFLINKSERRORLEVEL=ERROR --rm grafana/docs-base:latest /bin/bash -c 'make hugo'

.prettierignore

@@ -1,6 +1,11 @@
 .config
+
+# automatically generated
+CHANGELOG.md
+
 dist
 samples/static/grafana-pyroscope-sample-blocks-public*
+
 e2e/test-reports
 e2e/test-results
 

README.md

@@ -39,17 +39,18 @@ GF_INSTALL_PLUGINS=grafana-pyroscope-app
 2. You’ll land in the service overview page that shows time series and CPU utilization visualizations for all the services in your selected Pyroscope instance.
 3. Change your data source with the drop-down on the top left.
 4. Modify your time range in two ways:
-  * Use the standard time range picker on the top right.
-  * Click and drag the time range you want to see on any time series visualization.
-8. Select the service you would like to explore. This takes you to the Service page.
-9. Filter profiles based on labels.
 
-For more information, refer to the Explore Profiles documentation in [Grafana](https://grafana.com/docs/grafana/latest/explore/simplified-exploration/profiles/) or [Grafana Cloud](https://grafana.com/docs/grafana-cloud/visualizations/simplified-exploration/profiles/). 
+   - Use the standard time range picker on the top right.
+   - Click and drag the time range you want to see on any time series visualization.
 
-To learn more about contributing to the documentation, refer to the [README](https://github.com/grafana/explore-profiles/blob/main/docs/README.md). 
-The Explore Profiles documentation source files are in docs/sources. 
+5. Select the service you would like to explore. This takes you to the Service page.
+6. Filter profiles based on labels.
+
+For more information, refer to the Explore Profiles documentation in [Grafana](https://grafana.com/docs/grafana/latest/explore/simplified-exploration/profiles/) or [Grafana Cloud](https://grafana.com/docs/grafana-cloud/visualizations/simplified-exploration/profiles/).
+
+To learn more about contributing to the documentation, refer to the [README](https://github.com/grafana/explore-profiles/blob/main/docs/README.md).
+The Explore Profiles documentation source files are in docs/sources.
 
 ### Development / Contributing
 
 Check out our [Contributing Guidelines](./docs/CONTRIBUTING.md) for more information on how to contribute to this project.
-

docs/CONTRIBUTING.md

@@ -47,7 +47,7 @@ To enable this feature:
 2. Fill in the missing `GITHUB_` values in the `.env` file.
 3. Start the Grafana server.
 
-For more information, refer to the [Pyroscope GitHub integration](https://grafana.com/docs/grafana-cloud/monitor-applications/profiles/pyroscope-github-integration/) documentation. 
+For more information, refer to the [Pyroscope GitHub integration](https://grafana.com/docs/grafana-cloud/monitor-applications/profiles/pyroscope-github-integration/) documentation.
 
 ### Enable with live remote profile data
 

docs/sources/_index.md

@@ -42,7 +42,7 @@ cards:
       height: 24
     - title: Changelog
       href: https://github.com/grafana/explore-profiles/blob/main/CHANGELOG.md
-      description:  Learn about the updates, new features, and bugfixes in this version.
+      description: Learn about the updates, new features, and bugfixes in this version.
       height: 24
 ---
 
@@ -61,9 +61,9 @@ You don’t know what’s wrong, but you should be able to find it by drilling d
 
 Using Explore Profiles, you can:
 
-* View high-level service performance: Get a high-level view of all of your services and how they're functioning
-* Optimize processes: Identify processes or services that you can optimize for better performance
-* Diagnose issues: Determine the root cause of an issue
+- View high-level service performance: Get a high-level view of all of your services and how they're functioning
+- Optimize processes: Identify processes or services that you can optimize for better performance
+- Diagnose issues: Determine the root cause of an issue
 
 ## Explore
 

docs/sources/access/index.md

@@ -26,14 +26,14 @@ You can use Explore Profiles in Grafana Cloud or with Grafana open source stand-
 
 To use Explore Profiles with Grafana Cloud, you need:
 
-* A Grafana Cloud account
-* A Grafana stack in Grafana Cloud with a configured Hosted profiles or [Pyroscope data source](ref:pyroscope-data-source)
+- A Grafana Cloud account
+- A Grafana stack in Grafana Cloud with a configured Hosted profiles or [Pyroscope data source](ref:pyroscope-data-source)
 
 To use Explore Profiles with Grafana open source, you need:
 
-* Your own Grafana instance
-* A configured [Pyroscope data source](ref:pyroscope-data-source)
-* The [Explore Profiles plugin](https://grafana.com/grafana/plugins/grafana-pyroscope-app/)
+- Your own Grafana instance
+- A configured [Pyroscope data source](ref:pyroscope-data-source)
+- The [Explore Profiles plugin](https://grafana.com/grafana/plugins/grafana-pyroscope-app/)
 
 ## Install the Explore Profiles plugin
 
@@ -58,7 +58,8 @@ Alternatively, follow these steps to install Explore Profiles in Grafana:
 3. Select Explore Profiles.
 4. Click **Install**
 
-The plugin is automatically activated after installation. 
+The plugin is automatically activated after installation.
+
 ### Install using environment variables
 
 If you want to install the app in a Docker container, you need to configure the following environment variable:

docs/sources/concepts/index.md

@@ -19,29 +19,29 @@ weight: 200
 
 To use profiling, you should understand these concepts:
 
-* Profile data hierarchy
-* Profile types
-* Labels
-* Flame graphs
+- Profile data hierarchy
+- Profile types
+- Labels
+- Flame graphs
 
 ## Profile data hierarchy
 
 Each profile has data for services. A service can be one of the processes running on your system or application.
 
 Each service has multiple profile types, such as CPU, memory, exceptions, and locks. These profiles provide details about the processes in a service.
 
-* Service:  This is the main application or system you are monitoring. For example, it could be an online shopping platform, a social media application, or a cloud storage service.
-  * Profile type: You can monitor each service through different profile types, each focusing on a specific performance aspect. Example profile types:
-    * CPU
-    * allocated memory
-    * in-use memory
-    * goroutines
-  * Labels: These are tags or descriptors that provide additional context to the profile types. Labels help categorize and filter the data for easier analysis. For example:
-    * Namespace:
-    * Pod
-    * Instance
-    * IP
-    * Region
+- Service: This is the main application or system you are monitoring. For example, it could be an online shopping platform, a social media application, or a cloud storage service.
+  - Profile type: You can monitor each service through different profile types, each focusing on a specific performance aspect. Example profile types:
+    - CPU
+    - allocated memory
+    - in-use memory
+    - goroutines
+  - Labels: These are tags or descriptors that provide additional context to the profile types. Labels help categorize and filter the data for easier analysis. For example:
+    - Namespace:
+    - Pod
+    - Instance
+    - IP
+    - Region
 
 ## Profile types
 
@@ -50,13 +50,15 @@ Profile types refer to different dimensions of application performance analysis,
 For more information, refer to [Understand profiling types](https://grafana.com/docs/grafana-cloud/monitor-applications/profiles/introduction/profiling-types/).
 
 <!-- vale Grafana.Spelling = NO -->
-| Profile type | What it shows | When to use |
-|---|---|---|
-| CPU profiling | Measures the amount of CPU time consumed by different parts of your application code | To identify and optimize CPU-intensive functions |
-| Memory allocation  | Tracks the amount and frequency of memory allocations by the application | For identifying and optimizing memory usage patterns |
-| Goroutine | Measures the usage and performance of lightweight routines in Go | Especially useful in Go applications for concurrency management |
-| Contentions (Mutex) | Mutex profiling involves analyzing mutex (mutual exclusion) locks, used to prevent simultaneous access to shared resources. | To optimize thread synchronization and reduce lock contention |
-| Block | Measures the frequency and duration of blocking operations, where a thread is paused or delayed | To identify and reduce blocking delays |
+
+| Profile type        | What it shows                                                                                                               | When to use                                                     |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| CPU profiling       | Measures the amount of CPU time consumed by different parts of your application code                                        | To identify and optimize CPU-intensive functions                |
+| Memory allocation   | Tracks the amount and frequency of memory allocations by the application                                                    | For identifying and optimizing memory usage patterns            |
+| Goroutine           | Measures the usage and performance of lightweight routines in Go                                                            | Especially useful in Go applications for concurrency management |
+| Contentions (Mutex) | Mutex profiling involves analyzing mutex (mutual exclusion) locks, used to prevent simultaneous access to shared resources. | To optimize thread synchronization and reduce lock contention   |
+| Block               | Measures the frequency and duration of blocking operations, where a thread is paused or delayed                             | To identify and reduce blocking delays                          |
+
 <!-- vale Grafana.Spelling = NO -->
 
 ## Labels
@@ -73,9 +75,9 @@ A fundamental aspect of continuous profiling is the flame graph, a convenient wa
 
 You can use a flame graph visualization if you need to:
 
-* Identify any performance hot spots to find where code optimizations may be needed.
-* Diagnose the root cause of any performance degradation.
-* Analyze the behavior of complex systems, including distributed systems or microservices architectures.
+- Identify any performance hot spots to find where code optimizations may be needed.
+- Diagnose the root cause of any performance degradation.
+- Analyze the behavior of complex systems, including distributed systems or microservices architectures.
 
 To learn more, refer to the [Flame graph documentation](https://grafana.com/docs/grafana-cloud/monitor-applications/profiles/flamegraphs/).
 To learn more about the flame graph user interface, refer to [Flame graph visualization panel](ref:flame-graph-ui).

docs/sources/determine-use-case/index.md

@@ -14,8 +14,8 @@ weight: 400
 When you start investigating an issue, you may either know what's wrong (for example, you know the affected service or that there’s too much CPU usage), or you may want to explore data.
 This can lead you to two different starting points:
 
-* Use case 1 - You know which service has issues and you need to investigate why.
-* Use case 2 - You know there's a problem, but you need to locate where it is and the cause
+- Use case 1 - You know which service has issues and you need to investigate why.
+- Use case 2 - You know there's a problem, but you need to locate where it is and the cause
 
 Your use case determines what’s most important. If a service is misbehaving, then you might want to see the profile types so you can see the CPU and memory profiles alongside each other.
 

docs/sources/get-started/index.md

@@ -22,13 +22,13 @@ Your investigation begins with the big picture and then drills down using profil
 
 To use Explore Profiles with Grafana Cloud, you need:
 
-* A Grafana Cloud account
-* A Grafana stack in Grafana Cloud with a configured Hosted profiles or Pyroscope data source
+- A Grafana Cloud account
+- A Grafana stack in Grafana Cloud with a configured Hosted profiles or Pyroscope data source
 
 To use Explore Profiles with Grafana open source, you need:
 
-* Your own Grafana instance
-* Install [Explore Profiles plugin](https://grafana.com/grafana/plugins/grafana-pyroscope-app/)
+- Your own Grafana instance
+- Install [Explore Profiles plugin](https://grafana.com/grafana/plugins/grafana-pyroscope-app/)
 
 ## Explore your profile data
 
@@ -41,4 +41,4 @@ Most investigations follow four general steps:
 1. [Investigate trends and spikes](../investigate/).
 1. Identify issues, as the result of your investigation.
 
-{{< docs/play title="the Grafana Play site" url="https://play.grafana.org/a/grafana-pyroscope-app/profiles-explorer" >}}
+{{< docs/play title="the Grafana Play site" url="https://play.grafana.org/a/grafana-pyroscope-app/profiles-explorer" >}}

docs/sources/investigate/index.md

@@ -24,18 +24,17 @@ When you use Explore Profiles, your investigations follow these steps.
 1. Verify your data source in the **Data source** drop-down.
 1. Choose an **Exploration** type. **All services** is selected by default. Learn about the [available views](../choose-a-view/).
 1. Look for spikes or trends in the services to help identify issues. Use the **Profiles** drop-down to change profile types.
-  ![Select a profile type](../images/explore-profiles-flamegraph-2.png "Select a profile type")
+   ![Select a profile type](../images/explore-profiles-flamegraph-2.png 'Select a profile type')
 1. After you identify the service to explore, you can change views:
-   * Select **Profiles** to review the profiles for a service.
-   * Select **Labels** to view the labels for a service. The Labels view helps you gain an understanding at an aggregated service level.
-   * Select **Flame graph** to view the flame graph for a service.
+   - Select **Profiles** to review the profiles for a service.
+   - Select **Labels** to view the labels for a service. The Labels view helps you gain an understanding at an aggregated service level.
+   - Select **Flame graph** to view the flame graph for a service.
 1. Optional: Select filters to hone in on the problem areas. Each filter you select is added to the Filters statement at the top of the page. You can select filters in the following ways:
-   * Use the filter drop-downs in the Filters bar to add services and operators. Use **Execute** to run the filter.
-   * From the Labels view: Select **Add to filters** from one of the areas of interest.
+   - Use the filter drop-downs in the Filters bar to add services and operators. Use **Execute** to run the filter.
+   - From the Labels view: Select **Add to filters** from one of the areas of interest.
 1. Optional: Click and drag on any graph to select a specific time frame or data range.
 1. Use the **Labels** view to select two processes to compare.
-   * Select the checkbox in two graphs. Select **Compare** to view your selections in the **Comparison diff view**.
-   * Use the **Service** and **Profile** drop-downs to change the service or profile type displayed.
+   - Select the checkbox in two graphs. Select **Compare** to view your selections in the **Comparison diff view**.
+   - Use the **Service** and **Profile** drop-downs to change the service or profile type displayed.
 1. Use the **Flame graph** view to drill into the code level to pinpoint issues in specific functions, for example.
-  ![Viewing a flame graph during an investigation](../images/explore-profiles-flamegraph.png)
-
+   ![Viewing a flame graph during an investigation](../images/explore-profiles-flamegraph.png)

package.json

@@ -8,6 +8,7 @@
     "build": "webpack -c webpack.config.ts --env production",
     "predev": "rm -rf node_modules/.cache",
     "dev": "yarn predev && webpack -w -c webpack.config.ts --env development",
+    "docs:dev": "make -C docs docs",
     "e2e:ci": " docker run --network host -v $(pwd)/e2e:/app/e2e -v $(pwd)/src:/app/src pyroscope-app-plugin-e2e:latest",
     "e2e:ci:prepare": "docker build --progress=auto -t pyroscope-app-plugin-e2e:latest -f Dockerfile.plugin.e2e .",
     "e2e:ci:server:down": "docker-compose down",