chore(qol): Add a tag to extract a CONTRIBUTING.md section into a separate file--for example, frontmatter-reference--and reduce the size of `contributing.instructions.md`
Jason Stirnaman
parent
feb20c680b
commit
2ef37361a4
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,198 @@
|
|||
---
|
||||
applyTo: "content/**/*.md, layouts/**/*.html"
|
||||
---
|
||||
|
||||
### Complete Frontmatter Reference
|
||||
|
||||
Every documentation page includes frontmatter which specifies information about the page.
|
||||
Frontmatter populates variables in page templates and the site's navigation menu.
|
||||
|
||||
```yaml
|
||||
title: # Title of the page used in the page's h1
|
||||
seotitle: # Page title used in the html <head> title and used in search engine results
|
||||
list_title: # Title used in article lists generated using the {{< children >}} shortcode
|
||||
description: # Page description displayed in search engine results
|
||||
menu:
|
||||
influxdb_2_0:
|
||||
name: # Article name that only appears in the left nav
|
||||
parent: # Specifies a parent group and nests navigation items
|
||||
weight: # Determines sort order in both the nav tree and in article lists
|
||||
draft: # If true, will not render page on build
|
||||
product/v2.x/tags: # Tags specific to each version (replace product and .x" with the appropriate product and minor version )
|
||||
related: # Creates links to specific internal and external content at the bottom of the page
|
||||
- /path/to/related/article
|
||||
- https://external-link.com, This is an external link
|
||||
external_url: # Used in children shortcode type="list" for page links that are external
|
||||
list_image: # Image included with article descriptions in children type="articles" shortcode
|
||||
list_note: # Used in children shortcode type="list" to add a small note next to listed links
|
||||
list_code_example: # Code example included with article descriptions in children type="articles" shortcode
|
||||
list_query_example:# Code examples included with article descriptions in children type="articles" shortcode,
|
||||
# References to examples in data/query_examples
|
||||
canonical: # Path to canonical page, overrides auto-gen'd canonical URL
|
||||
v2: # Path to v2 equivalent page
|
||||
alt_links: # Alternate pages in other products/versions for cross-product navigation
|
||||
cloud-dedicated: /influxdb3/cloud-dedicated/path/to/page/
|
||||
core: /influxdb3/core/path/to/page/
|
||||
prepend: # Prepend markdown content to an article (especially powerful with cascade)
|
||||
block: # (Optional) Wrap content in a block style (note, warn, cloud)
|
||||
content: # Content to prepend to article
|
||||
append: # Append markdown content to an article (especially powerful with cascade)
|
||||
block: # (Optional) Wrap content in a block style (note, warn, cloud)
|
||||
content: # Content to append to article
|
||||
metadata: [] # List of metadata messages to include under the page h1
|
||||
updated_in: # Product and version the referenced feature was updated in (displayed as a unique metadata)
|
||||
source: # Specify a file to pull page content from (typically in /content/shared/)
|
||||
```
|
||||
|
||||
#### Title usage
|
||||
|
||||
##### `title`
|
||||
|
||||
The `title` frontmatter populates each page's HTML `h1` heading tag.
|
||||
It shouldn't be overly long, but should set the context for users coming from outside sources.
|
||||
|
||||
##### `seotitle`
|
||||
|
||||
The `seotitle` frontmatter populates each page's HTML `title` attribute.
|
||||
Search engines use this in search results (not the page's h1) and therefore it should be keyword optimized.
|
||||
|
||||
##### `list_title`
|
||||
|
||||
The `list_title` frontmatter determines an article title when in a list generated
|
||||
by the [`{{< children >}}` shortcode](#generate-a-list-of-children-articles).
|
||||
|
||||
##### `menu > name`
|
||||
|
||||
The `name` attribute under the `menu` frontmatter determines the text used in each page's link in the site navigation.
|
||||
It should be short and assume the context of its parent if it has one.
|
||||
|
||||
#### Page Weights
|
||||
|
||||
To ensure pages are sorted both by weight and their depth in the directory
|
||||
structure, pages should be weighted in "levels."
|
||||
All top level pages are weighted 1-99.
|
||||
The next level is 101-199.
|
||||
Then 201-299 and so on.
|
||||
|
||||
_**Note:** `_index.md` files should be weighted one level up from the other `.md` files in the same directory._
|
||||
|
||||
#### Related content
|
||||
|
||||
Use the `related` frontmatter to include links to specific articles at the bottom of an article.
|
||||
|
||||
- If the page exists inside of this documentation, just include the path to the page.
|
||||
It will automatically detect the title of the page.
|
||||
- If the page exists inside of this documentation, but you want to customize the link text,
|
||||
include the path to the page followed by a comma, and then the custom link text.
|
||||
The path and custom text must be in that order and separated by a comma and a space.
|
||||
- If the page exists outside of this documentation, include the full URL and a title for the link.
|
||||
The link and title must be in that order and separated by a comma and a space.
|
||||
|
||||
```yaml
|
||||
related:
|
||||
- /v2.0/write-data/quick-start
|
||||
- /v2.0/write-data/quick-start, This is custom text for an internal link
|
||||
- https://influxdata.com, This is an external link
|
||||
```
|
||||
|
||||
#### Canonical URLs
|
||||
|
||||
Search engines use canonical URLs to accurately rank pages with similar or identical content.
|
||||
The `canonical` HTML meta tag identifies which page should be used as the source of truth.
|
||||
|
||||
By default, canonical URLs are automatically generated for each page in the InfluxData
|
||||
documentation using the latest version of the current product and the current path.
|
||||
|
||||
Use the `canonical` frontmatter to override the auto-generated canonical URL.
|
||||
|
||||
_**Note:** The `canonical` frontmatter supports the [`{{< latest >}}` shortcode](#latest-links)._
|
||||
|
||||
```yaml
|
||||
canonical: /path/to/canonical/doc/
|
||||
|
||||
# OR
|
||||
|
||||
canonical: /{{< latest "influxdb" "v2" >}}/path/to/canonical/doc/
|
||||
```
|
||||
|
||||
#### v2 equivalent documentation
|
||||
|
||||
To display a notice on a 1.x page that links to an equivalent 2.0 page,
|
||||
add the following frontmatter to the 1.x page:
|
||||
|
||||
```yaml
|
||||
v2: /influxdb/v2.0/get-started/
|
||||
```
|
||||
|
||||
#### Alternative links for cross-product navigation
|
||||
|
||||
Use the `alt_links` frontmatter to specify equivalent pages in other InfluxDB products,
|
||||
for example, when a page exists at a different path in a different version or if
|
||||
the feature doesn't exist in that product.
|
||||
This enables the product switcher to navigate users to the corresponding page when they
|
||||
switch between products. If a page doesn't exist in another product (for example, an
|
||||
Enterprise-only feature), point to the nearest parent page if relevant.
|
||||
|
||||
```yaml
|
||||
alt_links:
|
||||
cloud-dedicated: /influxdb3/cloud-dedicated/admin/tokens/create-token/
|
||||
cloud-serverless: /influxdb3/cloud-serverless/admin/tokens/create-token/
|
||||
core: /influxdb3/core/reference/cli/influxdb3/update/ # Points to parent if exact page doesn't exist
|
||||
```
|
||||
|
||||
Supported product keys for InfluxDB 3:
|
||||
- `core`
|
||||
- `enterprise`
|
||||
- `cloud-serverless`
|
||||
- `cloud-dedicated`
|
||||
- `clustered`
|
||||
|
||||
#### Prepend and append content to a page
|
||||
|
||||
Use the `prepend` and `append` frontmatter to add content to the top or bottom of a page.
|
||||
Each has the following fields:
|
||||
|
||||
```yaml
|
||||
append: |
|
||||
> [!Note]
|
||||
> #### This is example markdown content
|
||||
> This is just an example note block that gets appended to the article.
|
||||
```
|
||||
|
||||
Use this frontmatter with [cascade](#cascade) to add the same content to
|
||||
all children pages as well.
|
||||
|
||||
```yaml
|
||||
cascade:
|
||||
append: |
|
||||
> [!Note]
|
||||
> #### This is example markdown content
|
||||
> This is just an example note block that gets appended to the article.
|
||||
```
|
||||
|
||||
#### Cascade
|
||||
|
||||
To automatically apply frontmatter to a page and all of its children, use the
|
||||
[`cascade` frontmatter](https://gohugo.io/content-management/front-matter/#front-matter-cascade)
|
||||
built in into Hugo.
|
||||
|
||||
```yaml
|
||||
title: Example page
|
||||
description: Example description
|
||||
cascade:
|
||||
layout: custom-layout
|
||||
```
|
||||
|
||||
`cascade` applies the frontmatter to all children unless the child already includes
|
||||
those frontmatter keys. Frontmatter defined on the page overrides frontmatter
|
||||
"cascaded" from a parent.
|
||||
|
||||
#### Use shared content in a page
|
||||
|
||||
Use the `source` frontmatter to specify a shared file to use to populate the
|
||||
page content. Shared files are typically stored in the `/content/shared` directory.
|
||||
|
||||
When building shared content, use the `show-in` and `hide-in` shortcodes to show
|
||||
or hide blocks of content based on the current InfluxDB product/version.
|
||||
For more information, see [show-in](#show-in) and [hide-in](#hide-in).
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,130 @@
|
|||
---
|
||||
applyTo: "content/**/*.md, layouts/**/*.html"
|
||||
---
|
||||
|
||||
### Detailed Testing Setup
|
||||
|
||||
#### Set up test scripts and credentials
|
||||
|
||||
Tests for code blocks require your InfluxDB credentials and other typical
|
||||
InfluxDB configuration.
|
||||
|
||||
To set up your docs-v2 instance to run tests locally, do the following:
|
||||
|
||||
1. **Set executable permissions on test scripts** in `./test/src`:
|
||||
|
||||
```sh
|
||||
chmod +x ./test/src/*.sh
|
||||
```
|
||||
|
||||
2. **Create credentials for tests**:
|
||||
|
||||
- Create databases, buckets, and tokens for the product(s) you're testing.
|
||||
- If you don't have access to a Clustered instance, you can use your
|
||||
Cloud Dedicated instance for testing in most cases. To avoid conflicts when
|
||||
running tests, create separate Cloud Dedicated and Clustered databases.
|
||||
|
||||
1. **Create .env.test**: Copy the `./test/env.test.example` file into each
|
||||
product directory to test and rename the file as `.env.test`--for example:
|
||||
|
||||
```sh
|
||||
./content/influxdb/cloud-dedicated/.env.test
|
||||
```
|
||||
|
||||
2. Inside each product's `.env.test` file, assign your InfluxDB credentials to
|
||||
environment variables:
|
||||
|
||||
- Include the usual `INFLUX_` environment variables
|
||||
- In
|
||||
`cloud-dedicated/.env.test` and `clustered/.env.test` files, also define the
|
||||
following variables:
|
||||
|
||||
- `ACCOUNT_ID`, `CLUSTER_ID`: You can find these values in your `influxctl`
|
||||
`config.toml` configuration file.
|
||||
- `MANAGEMENT_TOKEN`: Use the `influxctl management create` command to generate
|
||||
a long-lived management token to authenticate Management API requests
|
||||
|
||||
See the substitution
|
||||
patterns in `./test/src/prepare-content.sh` for the full list of variables you may need to define in your `.env.test` files.
|
||||
|
||||
3. For influxctl commands to run in tests, move or copy your `config.toml` file
|
||||
to the `./test` directory.
|
||||
|
||||
> [!Warning]
|
||||
>
|
||||
> - The database you configure in `.env.test` and any written data may
|
||||
be deleted during test runs.
|
||||
> - Don't add your `.env.test` files to Git. To prevent accidentally adding credentials to the docs-v2 repo,
|
||||
> Git is configured to ignore `.env*` files. Consider backing them up on your local machine in case of accidental deletion.
|
||||
|
||||
#### Test shell and python code blocks
|
||||
|
||||
[pytest-codeblocks](https://github.com/nschloe/pytest-codeblocks/tree/main) extracts code from python and shell Markdown code blocks and executes assertions for the code.
|
||||
If you don't assert a value (using a Python `assert` statement), `--codeblocks` considers a non-zero exit code to be a failure.
|
||||
|
||||
**Note**: `pytest --codeblocks` uses Python's `subprocess.run()` to execute shell code.
|
||||
|
||||
You can use this to test CLI and interpreter commands, regardless of programming
|
||||
language, as long as they return standard exit codes.
|
||||
|
||||
To make the documented output of a code block testable, precede it with the
|
||||
`<!--pytest-codeblocks:expected-output-->` tag and **omit the code block language
|
||||
descriptor**--for example, in your Markdown file:
|
||||
|
||||
##### Example markdown
|
||||
|
||||
```python
|
||||
print("Hello, world!")
|
||||
```
|
||||
|
||||
<!--pytest-codeblocks:expected-output-->
|
||||
|
||||
The next code block is treated as an assertion.
|
||||
If successful, the output is the following:
|
||||
|
||||
```
|
||||
Hello, world!
|
||||
```
|
||||
|
||||
For commands, such as `influxctl` CLI commands, that require launching an
|
||||
OAuth URL in a browser, wrap the command in a subshell and redirect the output
|
||||
to `/shared/urls.txt` in the container--for example:
|
||||
|
||||
```sh
|
||||
# Test the preceding command outside of the code block.
|
||||
# influxctl authentication requires TTY interaction--
|
||||
# output the auth URL to a file that the host can open.
|
||||
script -c "influxctl user list " \
|
||||
/dev/null > /shared/urls.txt
|
||||
```
|
||||
|
||||
You probably don't want to display this syntax in the docs, which unfortunately
|
||||
means you'd need to include the test block separately from the displayed code
|
||||
block.
|
||||
To hide it from users, wrap the code block inside an HTML comment.
|
||||
pytest-codeblocks will still collect and run the code block.
|
||||
|
||||
##### Mark tests to skip
|
||||
|
||||
pytest-codeblocks has features for skipping tests and marking blocks as failed.
|
||||
To learn more, see the pytest-codeblocks README and tests.
|
||||
|
||||
#### Troubleshoot tests
|
||||
|
||||
##### Pytest collected 0 items
|
||||
|
||||
Potential reasons:
|
||||
|
||||
- See the test discovery options in `pytest.ini`.
|
||||
- For Python code blocks, use the following delimiter:
|
||||
|
||||
```python
|
||||
# Codeblocks runs this block.
|
||||
```
|
||||
|
||||
`pytest --codeblocks` ignores code blocks that use the following:
|
||||
|
||||
```py
|
||||
# Codeblocks ignores this block.
|
||||
```
|
||||
|
||||
|
|
@ -114,9 +114,10 @@ docs-v2 contains a `./.vscode/settings.json` that configures the following exten
|
|||
|
||||
---
|
||||
|
||||
<!-- agent:instruct: essential -->
|
||||
<!-- agent:instruct: condense -->
|
||||
## Making Changes
|
||||
|
||||
|
||||
### Style Guidelines
|
||||
|
||||
#### Markdown
|
||||
|
|
@ -236,6 +237,19 @@ For the complete shortcodes reference with all available shortcodes, see [Comple
|
|||
|
||||
---
|
||||
|
||||
### InfluxDB API documentation
|
||||
|
||||
docs-v2 includes the InfluxDB API reference documentation in the `/api-docs` directory.
|
||||
To edit the API documentation, edit the YAML files in `/api-docs`.
|
||||
|
||||
InfluxData uses [Redoc](https://github.com/Redocly/redoc) to generate the full
|
||||
InfluxDB API documentation when documentation is deployed.
|
||||
Redoc generates HTML documentation using the InfluxDB `swagger.yml`.
|
||||
For more information about generating InfluxDB API documentation, see the
|
||||
[API Documentation README](https://github.com/influxdata/docs-v2/tree/master/api-docs#readme).
|
||||
|
||||
---
|
||||
|
||||
<!-- agent:instruct: condense -->
|
||||
## Testing & Quality Assurance
|
||||
|
||||
|
|
@ -296,7 +310,7 @@ docker compose run -T vale --config=content/influxdb/cloud-dedicated/.vale.ini -
|
|||
|
||||
---
|
||||
|
||||
<!-- agent:instruct: essential -->
|
||||
<!-- agent:instruct: condense -->
|
||||
## Submission Process
|
||||
|
||||
### Commit Guidelines
|
||||
|
|
@ -326,7 +340,7 @@ Push your changes up to your forked repository, then [create a new pull request]
|
|||
|
||||
## Reference Sections
|
||||
|
||||
<!-- agent:instruct: essential -->
|
||||
<!-- agent:instruct: extract frontmatter-reference.instructions.md -->
|
||||
### Complete Frontmatter Reference
|
||||
|
||||
Every documentation page includes frontmatter which specifies information about the page.
|
||||
|
|
@ -521,7 +535,7 @@ When building shared content, use the `show-in` and `hide-in` shortcodes to show
|
|||
or hide blocks of content based on the current InfluxDB product/version.
|
||||
For more information, see [show-in](#show-in) and [hide-in](#hide-in).
|
||||
|
||||
<!-- agent:instruct: essential -->
|
||||
<!-- agent:instruct: extract shortcodes-reference.instructions.md -->
|
||||
### Complete Shortcodes Reference
|
||||
|
||||
#### Notes and warnings
|
||||
|
|
@ -1079,6 +1093,9 @@ native file formats.
|
|||
````
|
||||
|
||||
##### Include specific files from the same directory
|
||||
> [!Caution]
|
||||
> #### Don't use for code examples
|
||||
> Using this and `get-shared-text` shortcodes to include code examples prevents the code from being tested.
|
||||
|
||||
To include the text from one file in another file in the same
|
||||
directory, use the `{{< get-leaf-text >}}` shortcode.
|
||||
|
|
@ -1703,7 +1720,7 @@ Replace the following:
|
|||
- {{% code-placeholder-key %}}`API_TOKEN`{{% /code-placeholder-key %}}: your [InfluxDB API token](/influxdb/v2/admin/tokens/)
|
||||
```
|
||||
|
||||
<!-- agent:instruct: condense -->
|
||||
<!-- agent:instruct: extract testing-setup.instructions.md -->
|
||||
### Detailed Testing Setup
|
||||
|
||||
#### Set up test scripts and credentials
|
||||
|
|
@ -1869,14 +1886,7 @@ To add accepted/rejected terms for specific products, configure a style for the
|
|||
|
||||
To learn more about configuration and rules, see [Vale configuration](https://vale.sh/docs/topics/config).
|
||||
|
||||
#### InfluxDB API documentation
|
||||
|
||||
InfluxData uses [Redoc](https://github.com/Redocly/redoc) to generate the full
|
||||
InfluxDB API documentation when documentation is deployed.
|
||||
Redoc generates HTML documentation using the InfluxDB `swagger.yml`.
|
||||
For more information about generating InfluxDB API documentation, see the
|
||||
[API Documentation README](https://github.com/influxdata/docs-v2/tree/master/api-docs#readme).
|
||||
|
||||
<!-- agent:instruct: condense -->
|
||||
#### JavaScript in the documentation UI
|
||||
|
||||
The InfluxData documentation UI uses JavaScript with ES6+ syntax and
|
||||
|
|
|
|||
|
|
@ -85,8 +85,17 @@ ${content}`;
|
|||
execSync(`git add "${instructionsPath}"`);
|
||||
console.log('✅ Added instructions file to git staging');
|
||||
}
|
||||
|
||||
// Also add any extracted files to git
|
||||
const extractedFiles = execSync(
|
||||
`git status --porcelain "${instructionsDir}/*.md"`
|
||||
).toString();
|
||||
if (extractedFiles.trim()) {
|
||||
execSync(`git add "${instructionsDir}"/*.md`);
|
||||
console.log('✅ Added extracted files to git staging');
|
||||
}
|
||||
} catch (error) {
|
||||
console.warn('⚠️ Could not add instructions file to git:', error.message);
|
||||
console.warn('⚠️ Could not add files to git:', error.message);
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -97,7 +106,7 @@ ${content}`;
|
|||
function optimizeContentForContext(content) {
|
||||
// Split content into sections based on agent:instruct tags
|
||||
const sections = [];
|
||||
const tagRegex = /<!-- agent:instruct: (essential|condense|remove) -->/g;
|
||||
const tagRegex = /<!-- agent:instruct: (essential|condense|remove|extract\s+\S+) -->/g;
|
||||
|
||||
let lastIndex = 0;
|
||||
let matches = [...content.matchAll(tagRegex)];
|
||||
|
|
@ -148,6 +157,14 @@ function optimizeContentForContext(content) {
|
|||
case 'remove':
|
||||
// Skip these sections entirely
|
||||
break;
|
||||
default:
|
||||
if (section.type.startsWith('extract ')) {
|
||||
const filename = section.type.substring(8); // Remove 'extract ' prefix
|
||||
processedContent += processExtractSection(section.content, filename);
|
||||
} else {
|
||||
processedContent += processUntaggedSection(section.content);
|
||||
}
|
||||
break;
|
||||
case 'untagged':
|
||||
processedContent += processUntaggedSection(section.content);
|
||||
break;
|
||||
|
|
@ -224,6 +241,39 @@ function condenseSection(content) {
|
|||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* Process extract sections to create separate files and placeholders
|
||||
*/
|
||||
function processExtractSection(content, filename) {
|
||||
// Remove the tag comment
|
||||
content = content.replace(/<!-- agent:instruct: extract \S+ -->\n?/g, '');
|
||||
|
||||
// Extract section header
|
||||
const headerMatch = content.match(/^(#+\s+.+)/m);
|
||||
if (!headerMatch) return content;
|
||||
|
||||
const header = headerMatch[1];
|
||||
const sectionTitle = header.replace(/^#+\s+/, '');
|
||||
|
||||
// Write the section content to a separate file
|
||||
const instructionsDir = path.join(process.cwd(), '.github', 'instructions');
|
||||
const extractedFilePath = path.join(instructionsDir, filename);
|
||||
|
||||
// Add frontmatter to the extracted file
|
||||
const extractedContent = `---
|
||||
applyTo: "content/**/*.md, layouts/**/*.html"
|
||||
---
|
||||
|
||||
${content}`;
|
||||
|
||||
fs.writeFileSync(extractedFilePath, extractedContent);
|
||||
|
||||
console.log(`✅ Extracted ${sectionTitle} to ${extractedFilePath}`);
|
||||
|
||||
// Create a placeholder that references the extracted file
|
||||
return `${header}\n\n_For the complete ${sectionTitle} reference, see ${filename}._\n\n`;
|
||||
}
|
||||
|
||||
/**
|
||||
* Process untagged sections with moderate optimization
|
||||
*/
|
||||
|
|
|
|||
Loading…
Reference in New Issue