[docs] Fix various syntax and rendering errors (#13653)

* fix various syntax and rendering issues

* more fixes

Author: colleenmcginnis

docs/docset.yml

@@ -37,3 +37,4 @@ subs:
   ml-init:   "ML"
   ilm-init:   "ILM"
   observability:   "Observability"
+  data-sources-cap: "Data views"

docs/extend/add-mapping.md

@@ -19,47 +19,45 @@ In the integration, the `fields` directory serves as the blueprint used to creat
 
 Like ingest pipelines, mappings only apply to the data stream dataset, for our example the `apache.access` dataset.
 
-+ NOTE: The names of these files are conventions, any file name with a `.yml` extension will work.
+:::{note}
+The names of these files are conventions, any file name with a `.yml` extension will work.
+:::
 
 Integrations have had significant enhancements in how ECS fields are defined. Below is a guide on which approach to use, based on the version of Elastic your integration will support.
 
-+ . ECS mappings component template (>=8.13.0) Integrations **only** supporting version 8.13.0 and up, can use the [ecs@mappings](https://github.com/elastic/elasticsearch/blob/c2a3ec42632b0339387121efdef13f52c6c66848/x-pack/plugin/core/template-resources/src/main/resources/ecs%40mappings.json) component template installed by Fleet. This makes explicitly declaring ECS fields unnecessary; the `ecs@mappings` component template in Elasticsearch will automatically detect and configure them. However, should ECS fields be explicitly defined, they will overwrite the dynamic mapping provided by the `ecs@mappings` component template. They can also be imported with an `external` declaration, as seen in the example below.
+1. ECS mappings component template (>=8.13.0) Integrations **only** supporting version 8.13.0 and up, can use the [ecs@mappings](https://github.com/elastic/elasticsearch/blob/c2a3ec42632b0339387121efdef13f52c6c66848/x-pack/plugin/core/template-resources/src/main/resources/ecs%40mappings.json) component template installed by Fleet. This makes explicitly declaring ECS fields unnecessary; the `ecs@mappings` component template in Elasticsearch will automatically detect and configure them. However, should ECS fields be explicitly defined, they will overwrite the dynamic mapping provided by the `ecs@mappings` component template. They can also be imported with an `external` declaration, as seen in the example below.
 
-+ . Dynamic mappings imports (<8.13.0 & >=8.13.0) Integrations supporting the Elastic stack below version 8.13.0 can still dynamically import ECS field mappings by defining `import_mappings: true` in the ECS section of the `_dev/build/build.yml` file in the root of the package directory. This introduces a [dynamic mapping](https://github.com/elastic/elastic-package/blob/f439b96a74c27c5adfc3e7810ad584204bfaf85d/internal/builder/_static/ecs_mappings.yaml) with most of the ECS definitions. Using this method means that, just like the previous approach, ECS fields don’t need to be defined in your integration, they are dynamically integrated into the package at build time. Explicitly defined ECS fields can be used and will also overwrite this mechanism.
+1. Dynamic mappings imports (<8.13.0 & >=8.13.0) Integrations supporting the Elastic stack below version 8.13.0 can still dynamically import ECS field mappings by defining `import_mappings: true` in the ECS section of the `_dev/build/build.yml` file in the root of the package directory. This introduces a [dynamic mapping](https://github.com/elastic/elastic-package/blob/f439b96a74c27c5adfc3e7810ad584204bfaf85d/internal/builder/_static/ecs_mappings.yaml) with most of the ECS definitions. Using this method means that, just like the previous approach, ECS fields don’t need to be defined in your integration, they are dynamically integrated into the package at build time. Explicitly defined ECS fields can be used and will also overwrite this mechanism.
 
-An example of the aformentioned `build.yml` file for this method:
+    An example of the aformentioned `build.yml` file for this method:
 
-+
-
-```yaml
-dependencies:
-  ecs:
-    reference: git@v8.6.0
-    import_mappings: true
-```
-
-+ . Explicit ECS mappings As mentioned in the previous two approaches, ECS mappings can still be set explicitly and will overwrite the dynamic mappings. This can be done in two ways: - Using an `external: ecs` reference to import the definition of a specific field. - Literally defining the ECS field.
+    ```yaml
+    dependencies:
+      ecs:
+        reference: git@v8.6.0
+        import_mappings: true
+    ```
 
-The `external: ecs` definition instructs the `elastic-package` command line tool to refer to an external ECS reference to resolve specific fields. By default it looks at the [ECS reference](https://raw.githubusercontent.com/elastic/ecs/v8.6.0/generated/ecs/ecs_nested.yml) file hosted on Github. This external reference file is determined by a Git reference found in the `_dev/build/build.yml` file, in the root of the package directory. The `build.yml` file set up for external references:
+1. Explicit ECS mappings As mentioned in the previous two approaches, ECS mappings can still be set explicitly and will overwrite the dynamic mappings. This can be done in two ways: - Using an `external: ecs` reference to import the definition of a specific field. - Literally defining the ECS field.
 
-+
+    The `external: ecs` definition instructs the `elastic-package` command line tool to refer to an external ECS reference to resolve specific fields. By default it looks at the [ECS reference](https://raw.githubusercontent.com/elastic/ecs/v8.6.0/generated/ecs/ecs_nested.yml) file hosted on Github. This external reference file is determined by a Git reference found in the `_dev/build/build.yml` file, in the root of the package directory. The `build.yml` file set up for external references:
 
-```yaml
-dependencies:
-  ecs:
-    reference: git@v8.6.0
-```
+    ```yaml
+    dependencies:
+      ecs:
+        reference: git@v8.6.0
+    ```
 
-Literal definition a ECS field:
+    Literal definition a ECS field:
 
-```yaml
-- name: cloud.acount.id
-  level: extended
-  type: keyword
-  ignore_above: 1024
-  description: 'The cloud account or organ....'
-  example: 43434343
-```
+    ```yaml
+    - name: cloud.acount.id
+      level: extended
+      type: keyword
+      ignore_above: 1024
+      description: 'The cloud account or organ....'
+      example: 43434343
+    ```
 
 1. Local ECS reference file (air-gapped setup) By changing the Git reference in in `_dev/build/build.yml` to the path of the downloaded [ECS reference](https://raw.githubusercontent.com/elastic/ecs/v8.6.0/generated/ecs/ecs_nested.yml) file, it is possible for the `elastic-package` command line tool to look for this file locally. Note that the path should be the full path to the reference file. Doing this, our `build.yml` file looks like:
 
@@ -72,9 +70,9 @@ Literal definition a ECS field:
 
 The `access` data stream dataset of the Apache integration has four different field definitions:
 
-+ NOTE: The `apache` integration below has not yet been updated to use the dynamic ECS field definition and uses `external` references to define ECS fields in `ecs.yml`.
-
-+
+:::{note}
+The `apache` integration below has not yet been updated to use the dynamic ECS field definition and uses `external` references to define ECS fields in `ecs.yml`.
+:::
 
 ```text
 apache
@@ -112,8 +110,6 @@ In this file, the `data_stream` subfields `type`, `dataset` and `namespace` are
 
 Here we define fields that we need in our integration and are not found in the ECS. The example below defines field `apache.access.ssl.protocol` in the Apache integration.
 
-+
-
 ```yaml
 - name: apache.access
   type: group

docs/extend/package-spec.md

@@ -31,18 +31,18 @@ In most scenarios, only data stream assets are needed. However, there are except
 
 The following assets are typically found in an Elastic package:
 
-* {es}
+* {{es}}
 
     * Ingest Pipeline
     * Index Template
     * Transform
     * Index template settings
 
-* {kib}
+* {{kib}}
 
     * Dashboards
     * Visualization
-    * {data-sources-cap}
+    * {{data-sources-cap}}
     * {{ml-init}} Modules
     * Map
     * Search

docs/extend/pipeline-testing.md

@@ -20,7 +20,9 @@ Conceptually, running a pipeline test involves the following steps:
 
 ## Limitations [pipeline-limitations]
 
-At the moment, pipeline tests have limitations. The main ones are: * As you’re only testing the ingest pipeline, you can prepare mocked documents with imaginary fields, different from ones collected in {{beats}}. Also, the other way round, you can skip most of the example fields and use tiny documents with a minimal set of fields just to satisfy the pipeline validation. * There might be integrations that transform data mainly using {{beats}} processors instead of ingest pipelines. In such cases, ingest pipelines are rather plain.
+At the moment, pipeline tests have limitations. The main ones are:
+* As you’re only testing the ingest pipeline, you can prepare mocked documents with imaginary fields, different from ones collected in {{beats}}. Also, the other way round, you can skip most of the example fields and use tiny documents with a minimal set of fields just to satisfy the pipeline validation.
+* There might be integrations that transform data mainly using {{beats}} processors instead of ingest pipelines. In such cases, ingest pipelines are rather plain.
 
 
 ## Defining a pipeline test [pipeline-defining-test]

docs/extend/quick-start.md

@@ -136,7 +136,7 @@ You’ve now built an integration package, but it does not contain any assets. F
 
         The command creates the required data in the `/data_stream/log` directory. If you pick `log` as data stream name, the dataset is called `sample.log` and the final data stream created will be `logs-sample.log-default` as an example.
 
-3. To not have to worry about mappings, you can pull in all [Elastic Common Schema (ECS) fields][Elastic Common Schema (ECS)](ecs://reference/index.md)). To do this, create the file `_dev/build/build.yml` under the root directory and add the following content:
+3. To not have to worry about mappings, you can pull in all [Elastic Common Schema (ECS) fields](ecs://reference/index.md). To do this, create the file `_dev/build/build.yml` under the root directory and add the following content:
 
     ```yaml
     dependencies:

docs/extend/testing-validation.md

@@ -105,8 +105,8 @@ The CI job runner collects coverage data and stores them together with build art
 
 As the Cobertura report format refers to packages, classes, methods, and such, unfortunately it doesn’t map easily onto the packages domain. We have decided to make a few assumptions for the Cobertura classification:
 
-* **Package**: `integration``
-* **File**: `data stream``
+* **Package**: `integration`
+* **File**: `data stream`
 * **Class**: test type (`pipeline tests`, `system tests`, etc.)
 * **Method**: "OK" if there are any tests present.
 

docs/extend/what-is-an-integration.md

@@ -20,7 +20,7 @@ Integrations have a strict, well-defined structure, and offer a number of benefi
 * Easy, less error-prone configuration
 * Fewer monitoring agents for users to install
 * Deploy in just a few clicks
-* Decoupled release process from the {stack}
+* Decoupled release process from the {{stack}}
 
 
 ## Integration lifecycle [how-integrations-work]