fix more headers

Blargian · Blargian · commit 62db487d1ebe · 2025-07-13T13:12:28.000+02:00
diff --git a/contribute/style-guide.md b/contribute/style-guide.md
@@ -393,3 +393,22 @@ show_related_blogs: true
 
 This will show it on the page, assuming there is a matching blog. If there is no
 match then it remains hidden.
+
+## Vale
+
+Vale is a command-line tool that brings code-like linting to prose.
+We have a number of rules set up to ensure that our documentation is
+consistent in style.
+
+The style rules are located at `/styles/ClickHouse`, and largely based
+off of the Google styleset, with some ClickHouse specific adaptions.
+If you want to check only a specific rule locally, you
+can run:
+
+```bash
+vale --filter='.Name == "ClickHouse.Headings"' docs/integrations
+```
+
+This will run only the rule named `Headings` on
+the `docs/integrations` directory. Specifying a specific markdown
+file is also possible.
diff --git a/docs/integrations/data-ingestion/gcs/index.md b/docs/integrations/data-ingestion/gcs/index.md
@@ -25,7 +25,7 @@ ClickHouse recognizes that GCS represents an attractive storage solution for use
 
 To utilize a GCS bucket as a disk, we must first declare it within the ClickHouse configuration in a file under `conf.d`. An example of a GCS disk declaration is shown below.  This configuration includes multiple sections to configure the GCS "disk", the cache, and the policy that is specified in DDL queries when tables are to be created on the GCS disk.  Each of these are described below.
 
-#### storage_configuration > disks > gcs {#storage_configuration--disks--gcs}
+#### Storage configuration > disks > gcs {#storage_configuration--disks--gcs}
 
 This part of the configuration is shown in the highlighted section and specifies that:
 - Batch deletes are not to be performed.  GCS does not currently support batch deletes, so the autodetect is disabled to suppress error messages.
@@ -61,7 +61,7 @@ This part of the configuration is shown in the highlighted section and specifies
     </storage_configuration>
 </clickhouse>
 ```
-#### storage_configuration > disks > cache {#storage_configuration--disks--cache}
+#### Storage configuration > disks > cache {#storage_configuration--disks--cache}
 
 The example configuration highlighted below enables a 10Gi memory cache for the disk `gcs`.
 
@@ -98,7 +98,7 @@ The example configuration highlighted below enables a 10Gi memory cache for the
     </storage_configuration>
 </clickhouse>
 ```
-#### storage_configuration > policies > gcs_main {#storage_configuration--policies--gcs_main}
+#### Storage configuration > policies > gcs_main {#storage_configuration--policies--gcs_main}
 
 Storage configuration policies allow choosing where data is stored.  The policy highlighted below allows data to be stored on the disk `gcs` by specifying the policy `gcs_main`.  For example, `CREATE TABLE ... SETTINGS storage_policy='gcs_main'`.
 
diff --git a/docs/integrations/data-ingestion/google-dataflow/templates.md b/docs/integrations/data-ingestion/google-dataflow/templates.md
@@ -8,7 +8,7 @@ title: 'Google Dataflow Templates'
 
 import ClickHouseSupportedBadge from '@theme/badges/ClickHouseSupported';
 
-# Google Dataflow Templates
+# Google Dataflow templates
 
 <ClickHouseSupportedBadge/>
 
diff --git a/docs/integrations/data-ingestion/kafka/kafka-table-engine.md b/docs/integrations/data-ingestion/kafka/kafka-table-engine.md
@@ -484,7 +484,7 @@ Consider the following when looking to increase Kafka Engine table throughput pe
 
 Any settings changes should be tested. We recommend monitoring Kafka consumer lags to ensure you are properly scaled.
 
-#### Additional Settings {#additional-settings}
+#### Additional settings {#additional-settings}
 
 Aside from the settings discussed above, the following may be of interest:
 
diff --git a/docs/integrations/data-ingestion/s3/performance.md b/docs/integrations/data-ingestion/s3/performance.md
@@ -187,7 +187,7 @@ In our example we only return a few rows. If measuring the performance of `SELEC
 When reading from queries, the initial query can often appear slower than if the same query is repeated. This can be attributed to both S3's own caching but also the [ClickHouse Schema Inference Cache](/operations/system-tables/schema_inference_cache). This stores the inferred schema for files and means the inference step can be skipped on subsequent accesses, thus reducing query time.
 :::
 
-## Using Threads for Reads {#using-threads-for-reads}
+## Using threads for reads {#using-threads-for-reads}
 
 Read performance on S3 will scale linearly with the number of cores, provided you are not limited by network bandwidth or local I/O. Increasing the number of threads also has memory overhead permutations that users should be aware of. The following can be modified to improve read throughput performance potentially:
 
@@ -233,7 +233,7 @@ SETTINGS max_threads = 64
 Peak memory usage: 639.99 MiB.
 ```
 
-## Tuning Threads and Block Size for Inserts {#tuning-threads-and-block-size-for-inserts}
+## Tuning threads and block size for inserts {#tuning-threads-and-block-size-for-inserts}
 
 To achieve maximum ingestion performance, you must choose (1) an insert block size and (2) an appropriate level of insert parallelism based on (3) the amount of available CPU cores and RAM available. In summary:
 
@@ -270,7 +270,7 @@ FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/stackoverflow
 
 As shown, tuning of these setting has improved insert performance by over `33%`. We leave this to the reader to see if they can improve single node performance further.
 
-## Scaling with Resources and Nodes {#scaling-with-resources-and-nodes}
+## Scaling with resources and nodes {#scaling-with-resources-and-nodes}
 
 Scaling with resources and nodes applies to both read and insert queries.
 
diff --git a/docs/integrations/data-visualization/hashboard-and-clickhouse.md b/docs/integrations/data-visualization/hashboard-and-clickhouse.md
@@ -49,6 +49,6 @@ This guide will walk you through the steps to connect Hashboard with your ClickH
 
 Your ClickHouse database is now be connected to Hashboard and you can proceed by building [Data Models](https://docs.hashboard.com/docs/data-modeling/add-data-model), [Explorations](https://docs.hashboard.com/docs/visualizing-data/explorations), [Metrics](https://docs.hashboard.com/docs/metrics), and [Dashboards](https://docs.hashboard.com/docs/dashboards). See the corresponding Hashboard documentation for more detail on these features.
 
-## Learn More {#learn-more}
+## Learn more {#learn-more}
 
 For more advanced features and troubleshooting, visit [Hashboard's documentation](https://docs.hashboard.com/).
diff --git a/docs/integrations/data-visualization/rocketbi-and-clickhouse.md b/docs/integrations/data-visualization/rocketbi-and-clickhouse.md
@@ -137,7 +137,7 @@ Save & Add the Chart to Dashboard
 
 <Image size="md" img={rocketbi_14} alt="Dashboard view showing the newly added pie chart with other controls" border />
 
-#### Use Date Control in a Time-series Chart {#use-date-control-in-a-time-series-chart}
+#### Use date control in a time-series chart {#use-date-control-in-a-time-series-chart}
 Let Use a Stacked Column Chart
 
 <Image size="md" img={rocketbi_15} alt="Stacked column chart creation interface with time-series data" border />
diff --git a/docs/integrations/data-visualization/tableau/tableau-online-and-clickhouse.md b/docs/integrations/data-visualization/tableau/tableau-online-and-clickhouse.md
@@ -56,7 +56,7 @@ After that, all that remains is to click "Publish As" in the top right corner, a
 
 NB: if you want to use Tableau Online in combination with Tableau Desktop and share ClickHouse datasets between them, make sure you use Tableau Desktop with the default MySQL connector as well, following the setup guide that is displayed [here](https://www.tableau.com/support/drivers) if you select MySQL from the Data Source drop-down. If you have an M1 Mac, check [this troubleshooting thread](https://community.tableau.com/s/question/0D58b0000Ar6OhvCQE/unable-to-install-mysql-driver-for-m1-mac) for a driver installation workaround.
 
-## Connecting Tableau Online to ClickHouse (Cloud or on-premise setup with SSL) {#connecting-tableau-online-to-clickhouse-cloud-or-on-premise-setup-with-ssl}
+## Connecting Tableau Online to ClickHouse (cloud or on-premise setup with SSL) {#connecting-tableau-online-to-clickhouse-cloud-or-on-premise-setup-with-ssl}
 
 As it is not possible to provide the SSL certificates via the Tableau Online MySQL connection setup wizard, 
 the only way is to use Tableau Desktop to set the connection up, and then export it to Tableau Online. This process is, however, pretty straightforward.
diff --git a/docs/integrations/language-clients/python/index.md b/docs/integrations/language-clients/python/index.md
@@ -415,7 +415,7 @@ efficiently. This method takes the following parameters.
 | external_data       | ExternalData     | *None*     | An ExternalData object containing file or binary data to use with the query.  See [Advanced Queries (External Data)](#external-data)                                               |
 | context             | QueryContext     | *None*     | A reusable QueryContext object can be used to encapsulate the above method arguments. See [Advanced Queries (QueryContexts)](#querycontexts)                                       |
 
-#### The QueryResult Object {#the-queryresult-object}
+#### The QueryResult object {#the-queryresult-object}
 
 The base `query` method returns a QueryResult object with the following public properties:
 
diff --git a/docs/integrations/migration/clickhouse-to-cloud.md b/docs/integrations/migration/clickhouse-to-cloud.md
@@ -198,7 +198,7 @@ Modify the allow list and allow access from **Anywhere** temporarily. See the [I
 
 - Verify the data in the destination service
 
-#### Re-establish the IP Access List on the source {#re-establish-the-ip-access-list-on-the-source}
+#### Re-establish the IP access list on the source {#re-establish-the-ip-access-list-on-the-source}
 
   If you exported the access list earlier, then you can re-import it using **Share**, otherwise re-add your entries to the access list.
 
diff --git a/docs/use-cases/observability/build-your-own/grafana.md b/docs/use-cases/observability/build-your-own/grafana.md
@@ -83,7 +83,7 @@ This query returns the column names expected by Grafana, rendering a table of tr
 
 Users wishing to write more complex queries can switch to the `SQL Editor`.
 
-### View Trace details {#view-trace-details}
+### View trace details {#view-trace-details}
 
 As shown above, Trace ids are rendered as clickable links. On clicking on a trace Id, a user can choose to view the associated spans via the link `View Trace`. This issues the following query (assuming OTel columns) to retrieve the spans in the required structure, rendering the results as a waterfall.
 
diff --git a/docs/use-cases/observability/build-your-own/integrating-opentelemetry.md b/docs/use-cases/observability/build-your-own/integrating-opentelemetry.md
@@ -15,7 +15,7 @@ import observability_8 from '@site/static/images/use-cases/observability/observa
 import observability_9 from '@site/static/images/use-cases/observability/observability-9.png';
 import Image from '@theme/IdealImage';
 
-# Integrating OpenTelemetry for Data Collection
+# Integrating OpenTelemetry for data collection
 
 Any Observability solution requires a means of collecting and exporting logs and traces. For this purpose, ClickHouse recommends [the OpenTelemetry (OTel) project](https://opentelemetry.io/).
 
@@ -83,7 +83,7 @@ This approach requires users to instrument their code with their [appropriate la
 [`otelbin.io`](https://www.otelbin.io/) is useful to validate and visualize configurations.
 :::
 
-## Structured vs Unstructured {#structured-vs-unstructured}
+## Structured vs unstructured {#structured-vs-unstructured}
 
 Logs can either be structured or unstructured.
 
@@ -202,7 +202,7 @@ The above messages don't have a `TraceID` or `SpanID` field. If present, e.g. in
 
 For users needing to collect local or Kubernetes log files, we recommend users become familiar with the configuration options available for the [filelog receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/filelogreceiver/README.md#configuration) and how [offsets](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/filelogreceiver#offset-tracking) and [multiline log parsing is handled](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/filelogreceiver#example---multiline-logs-parsing).
 
-## Collecting Kubernetes Logs {#collecting-kubernetes-logs}
+## Collecting Kubernetes logs {#collecting-kubernetes-logs}
 
 For the collection of Kubernetes logs, we recommend the [OpenTelemetry documentation guide](https://opentelemetry.io/docs/kubernetes/). The [Kubernetes Attributes Processor](https://opentelemetry.io/docs/kubernetes/collector/components/#kubernetes-attributes-processor) is recommended for enriching logs and metrics with pod metadata. This can potentially produce dynamic metadata e.g. labels, stored in the column `ResourceAttributes`. ClickHouse currently uses the type `Map(String, String)` for this column. See [Using Maps](/use-cases/observability/schema-design#using-maps) and [Extracting from maps](/use-cases/observability/schema-design#extracting-from-maps) for further details on handling and optimizing this type.
 
@@ -602,7 +602,7 @@ From the collector's perspective, (1) and (2) can be hard to distinguish. Howeve
 
 We recommend users use the [batch processor](https://github.com/open-telemetry/opentelemetry-collector/blob/main/processor/batchprocessor/README.md) shown in earlier configurations to satisfy the above. This ensures inserts are sent as consistent batches of rows satisfying the above requirements. If a collector is expected to have high throughput (events per second), and at least 5000 events can be sent in each insert, this is usually the only batching required in the pipeline. In this case the collector will flush batches before the batch processor's `timeout` is reached, ensuring the end-to-end latency of the pipeline remains low and batches are of a consistent size.
 
-### Use Asynchronous inserts {#use-asynchronous-inserts}
+### Use asynchronous inserts {#use-asynchronous-inserts}
 
 Typically, users are forced to send smaller batches when the throughput of a collector is low, and yet they still expect data to reach ClickHouse within a minimum end-to-end latency. In this case, small batches are sent when the `timeout` of the batch processor expires. This can cause problems and is when asynchronous inserts are required. This case typically arises when **collectors in the agent role are configured to send directly to ClickHouse**. Gateways, by acting as aggregators, can alleviate this problem - see [Scaling with Gateways](#scaling-with-gateways).
 
@@ -624,7 +624,7 @@ Finally, the previous deduplication behavior associated with synchronous inserts
 
 Full details on configuring this feature can be found [here](/optimize/asynchronous-inserts#enabling-asynchronous-inserts), with a deep dive [here](https://clickhouse.com/blog/asynchronous-data-inserts-in-clickhouse).
 
-## Deployment Architectures {#deployment-architectures}
+## Deployment architectures {#deployment-architectures}
 
 Several deployment architectures are possible when using the OTel collector with Clickhouse. We describe each below and when it is likely applicable.
 
@@ -642,7 +642,7 @@ Users should consider migrating to a Gateway-based architecture once the number
 - **Processing at the edge** - Any transformations or event processing has to be performed at the edge or in ClickHouse in this architecture. As well as being restrictive this can either mean complex ClickHouse materialized views or pushing significant computation to the edge - where critical services may be impacted and resources scarce.
 - **Small batches and latencies** - Agent collectors may individually collect very few events. This typically means they need to be configured to flush at a set interval to satisfy delivery SLAs. This can result in the collector sending small batches to ClickHouse. While a disadvantage, this can be mitigated with Asynchronous inserts - see [Optimizing inserts](#optimizing-inserts).
 
-### Scaling with Gateways {#scaling-with-gateways}
+### Scaling with gateways {#scaling-with-gateways}
 
 OTel collectors can be deployed as Gateway instances to address the above limitations. These provide a standalone service, typically per data center or per region. These receive events from applications (or other collectors in the agent role) via a single OTLP endpoint. Typically a set of gateway instances are deployed, with an out-of-the-box load balancer used to distribute the load amongst them.
 
diff --git a/docs/use-cases/observability/build-your-own/introduction.md b/docs/use-cases/observability/build-your-own/introduction.md
@@ -10,7 +10,7 @@ import observability_1 from '@site/static/images/use-cases/observability/observa
 import observability_2 from '@site/static/images/use-cases/observability/observability-2.png';
 import Image from '@theme/IdealImage';
 
-# Using ClickHouse for Observability
+# Using ClickHouse for observability
 
 ## Introduction {#introduction}
 
@@ -84,7 +84,7 @@ We currently recommend ClickHouse for storing two types of observability data:
 While ClickHouse can be used to store metrics data, this pillar is less mature in ClickHouse with pending support for features such as support for the Prometheus data format and PromQL.
 :::
 
-### Distributed Tracing {#distributed-tracing}
+### Distributed tracing {#distributed-tracing}
 
 Distributed tracing is a critical feature of Observability. A distributed trace, simply called a trace, maps the journey of a request through a system. The request will originate from an end user or application and proliferate throughout a system, typically resulting in a flow of actions between microservices. By recording this sequence, and allowing the subsequent events to be correlated, it allows an observability user or SRE to be able to diagnose issues in an application flow irrespective of how complex or serverless the architecture is.
 
diff --git a/docs/use-cases/observability/build-your-own/managing-data.md b/docs/use-cases/observability/build-your-own/managing-data.md
@@ -10,7 +10,7 @@ import observability_14 from '@site/static/images/use-cases/observability/observ
 import Image from '@theme/IdealImage';
 
 
-# Managing Data
+# Managing data
 
 Deployments of ClickHouse for Observability invariably involve large datasets, which need to be managed. ClickHouse offers a number of features to assist with data management.
 
@@ -153,7 +153,7 @@ The above illustrates how data can be efficiently moved and manipulated by parti
 
 We explore both of these in detail below.
 
-### Query Performance {#query-performance}
+### Query performance {#query-performance}
 
 While partitions can assist with query performance, this depends heavily on the access patterns. If queries target only a few partitions (ideally one), performance can potentially improve. This is only typically useful if the partitioning key is not in the primary key and you are filtering by it. However, queries which need to cover many partitions may perform worse than if no partitioning is used (as there may possibly be more parts). The benefit of targeting a single partition will be even less pronounced to non-existent if the partitioning key is already an early entry in the primary key. Partitioning can also be used to [optimize GROUP BY queries](/engines/table-engines/mergetree-family/custom-partitioning-key#group-by-optimisation-using-partition-key) if values in each partition are unique. However, in general, users should ensure the primary key is optimized and only consider partitioning as a query optimization technique in exceptional cases where access patterns access a specific predictable subset of the data, e.g., partitioning by day, with most queries in the last day. See [here](https://medium.com/datadenys/using-partitions-in-clickhouse-3ea0decb89c4) for an example of this behavior.
 
diff --git a/docs/use-cases/observability/build-your-own/schema-design.md b/docs/use-cases/observability/build-your-own/schema-design.md
diff --git a/docs/use-cases/observability/index.md b/docs/use-cases/observability/index.md
diff --git a/docs/use-cases/time-series/analysis-functions.md b/docs/use-cases/time-series/analysis-functions.md
diff --git a/docs/use-cases/time-series/query-performance.md b/docs/use-cases/time-series/query-performance.md
diff --git a/docs/use-cases/time-series/storage-efficiency.md b/docs/use-cases/time-series/storage-efficiency.md
diff --git a/styles/ClickHouse/Headings.yml b/styles/ClickHouse/Headings.yml
