Document and fix indented data refs (#38806)

content/code-security/codeql-cli/using-the-codeql-cli/testing-custom-queries.md

@@ -143,7 +143,7 @@ other custom queries. For example, `custom-queries/java/queries/EmptyThen.ql`.
 
 1. Create a {% data variables.product.prodname_codeql %} pack for your Java tests by adding a `qlpack.yml` file with the following contents to `custom-queries/java/tests`, updating the `dependencies` to match the name of your {% data variables.product.prodname_codeql %} pack of custom queries:
 
-  {% data reusables.codeql-cli.test-qlpack %}
+{% indented_data_reference reusables.codeql-cli.test-qlpack spaces=2 %}
 
 1. Run `codeql pack install` in the root of the test directory. This generates a `codeql-pack.lock.yml` file that specifies all of the transitive dependencies required to run queries in this pack.
 

contributing/content-style-guide.md

@@ -137,6 +137,8 @@ In YAML examples, such as actions and workflow files, use two spaces to indent l
           python-version: {% raw %}${{ matrix.python }}{% endraw %}
 ```
 
+To indent reusables, see [`data/reusables/README.md`](/data/reusables/README.md).
+
 ### Scheduled workflows
 
 Workflow runs are delayed when too many workflows run at once. Since many users copy code from the GitHub docs, we should use examples that guide users away from congested times.

data/reusables/README.md

@@ -12,6 +12,18 @@ For example, a file named `/data/reusables/foo/bar.md` will be accessible as `{%
 
 Reusable files are divided generally into directories by task. For example, if you're creating a reusable string for articles about GitHub notifications, you'd add it in the directory `data/reusables/notifications/` in a file named `data/reusables/notifications/your-reusable-name.md`. The content reference you'd add to the source would look like `{% data reusables.notifications.your-reusable-name %}`.
 
+## Indenting
+
+Indented reusables require a special liquid tag: `indented_data_reference` which also requires the number of spaces to indent as an argument.
+
+For example, to indent `/data/reusables/foo/bar.md` in an ordered list, you could:
+
+```md
+1. My first list item
+{% indented_data_reference reusables.foo.par spaces=2 %}
+1. My second list item
+```
+
 ## Versioning
 
 Reusables can include Liquid conditionals to conditionally render content depending on the current version being viewed. See [contributing/liquid-helpers.md](/contributing/liquid-helpers.md).

data/reusables/codeql-cli/test-qlpack.md

@@ -1,9 +1,9 @@
 The following `qlpack.yml` file states that `my-github-user/my-query-tests` depends on `my-github-user/my-custom-queries` at a version greater than or equal to 1.2.3 and less than 2.0.0. It also declares that the CLI should use the Java `extractor` when creating test databases. The `tests: .` line declares that all `.ql` files in the pack should be run as tests when `codeql test run` is run with the `--strict-test-discovery` option. Typically, test packs do not contain a `version` property. This prevents you from accidentally publishing them.
 
 ```yaml
-  name: my-github-user/my-query-tests
-  dependencies:
-    my-github-user/my-custom-queries: ^1.2.3
-  extractor: java
-  tests: .
+name: my-github-user/my-query-tests
+dependencies:
+  my-github-user/my-custom-queries: ^1.2.3
+extractor: java
+tests: .
 ```