Skip to content

Commit eb71682

Browse files
hectorsectorhectorsector
authored
Document and fix indented data refs (github#38806)
1 parent 6eee2ba commit eb71682

4 files changed

Lines changed: 29 additions & 15 deletions

File tree

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,7 @@ other custom queries. For example, `custom-queries/java/queries/EmptyThen.ql`.
143143

144144
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:
145145

146-
{% data reusables.codeql-cli.test-qlpack %}
146+
{% indented_data_reference reusables.codeql-cli.test-qlpack spaces=2 %}
147147

148148
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.
149149

@@ -166,7 +166,7 @@ which is declared as a dependency for `my-query-tests`. Therefore, `EmptyThen.ql
166166
System.out.println("Empty argument");
167167
}
168168
}
169-
169+
170170
public void good(String arg) {
171171
if (arg.isEmpty()) {
172172
System.out.println("Empty argument");

‎contributing/content-style-guide.md‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -137,6 +137,8 @@ In YAML examples, such as actions and workflow files, use two spaces to indent l
137137
python-version: {% raw %}${{ matrix.python }}{% endraw %}
138138
```
139139

140+
To indent reusables, see [`data/reusables/README.md`](/data/reusables/README.md).
141+
140142
### Scheduled workflows
141143

142144
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.
@@ -151,7 +153,7 @@ Use italics to emphasize words or parts of a sentence. Use emphasis sparingly fo
151153

152154
- **Use:** _Fine-grained personal access tokens_ have several security advantages over personal access tokens (classic).
153155
- **Use:** _For types of packages other than containers_, to the right of the package version click **Delete**.
154-
- **Avoid:** Next to _**Title**_, add a descriptive label for your new key.
156+
- **Avoid:** Next to _**Title**_, add a descriptive label for your new key.
155157

156158
## Footnotes
157159

@@ -893,7 +895,7 @@ For example, in "[Autoscaling with self hosted runners](https://docs.github.com/
893895
894896
### Use proper markup for row and column headers
895897
896-
Tables in which the first column describes the data values in the table (but is not data itself) need to be marked up with row headers. This is important for assistive technology to understand relationships between cells.
898+
Tables in which the first column describes the data values in the table (but is not data itself) need to be marked up with row headers. This is important for assistive technology to understand relationships between cells.
897899
898900
For example in the following table, in order to make sense of the "Yes" and "No" values in the table, you need to know both the column header (role) and row header (permission).
899901
@@ -955,11 +957,11 @@ See "[Footnotes](https://github.com/github/docs/blob/main/contributing/content-s
955957
956958
### Align table content consistently
957959
958-
All columns in a table should be left-aligned, except for columns containing only octicons which should be center-aligned. If a column contains both text and octicons, use center alignment.
960+
All columns in a table should be left-aligned, except for columns containing only octicons which should be center-aligned. If a column contains both text and octicons, use center alignment.
959961
960962
Table content is left-aligned by default. Use Markdown table formatting, colons (`:`) to either the right or left of the dashes in the header row, to specify the alignment of each column. Read "[Organizing information with tables](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-tables#formatting-content-within-your-table)" for more information.
961963
962-
The following example shows part of a table from "[Configuration options for the dependabot.yml file](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file)".
964+
The following example shows part of a table from "[Configuration options for the dependabot.yml file](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file)".
963965
964966
965967
<table>
@@ -994,7 +996,7 @@ The following example shows part of a table from "[Configuration options for the
994996
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/github/docs-internal/assets/12902836/fd97adaf-5ac5-4da0-9de1-89d70f0edc45">
995997
<source media="(prefers-color-scheme: light)" srcset="https://github.com/github/docs-internal/assets/12902836/6e531ef9-275b-4630-8217-3a2399e450bf">
996998
<img alt="Supported">
997-
</picture>
999+
</picture>
9981000
</td>
9991001
<td align=left>Package manager to use</td>
10001002
</tr>
@@ -1005,8 +1007,8 @@ The following example shows part of a table from "[Configuration options for the
10051007
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/github/docs-internal/assets/12902836/fd97adaf-5ac5-4da0-9de1-89d70f0edc45">
10061008
<source media="(prefers-color-scheme: light)" srcset="https://github.com/github/docs-internal/assets/12902836/6e531ef9-275b-4630-8217-3a2399e450bf">
10071009
<img alt="Supported">
1008-
</picture>
1009-
</td>
1010+
</picture>
1011+
</td>
10101012
</td>
10111013
<td align=center>
10121014
<picture>
@@ -1032,7 +1034,7 @@ The following example shows part of a table from "[Configuration options for the
10321034
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/github/docs-internal/assets/12902836/fd97adaf-5ac5-4da0-9de1-89d70f0edc45">
10331035
<source media="(prefers-color-scheme: light)" srcset="https://github.com/github/docs-internal/assets/12902836/6e531ef9-275b-4630-8217-3a2399e450bf">
10341036
<img alt="Supported">
1035-
</picture>
1037+
</picture>
10361038
</td>
10371039
</td>
10381040
<td align=center>

‎data/reusables/README.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,18 @@ For example, a file named `/data/reusables/foo/bar.md` will be accessible as `{%
1212

1313
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 %}`.
1414

15+
## Indenting
16+
17+
Indented reusables require a special liquid tag: `indented_data_reference` which also requires the number of spaces to indent as an argument.
18+
19+
For example, to indent `/data/reusables/foo/bar.md` in an ordered list, you could:
20+
21+
```md
22+
1. My first list item
23+
{% indented_data_reference reusables.foo.par spaces=2 %}
24+
1. My second list item
25+
```
26+
1527
## Versioning
1628

1729
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‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
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.
22

33
```yaml
4-
name: my-github-user/my-query-tests
5-
dependencies:
6-
my-github-user/my-custom-queries: ^1.2.3
7-
extractor: java
8-
tests: .
4+
name: my-github-user/my-query-tests
5+
dependencies:
6+
my-github-user/my-custom-queries: ^1.2.3
7+
extractor: java
8+
tests: .
99
```

0 commit comments

Comments
 (0)