chore(docs): Redesign docs CLI tools for creating and editing content, add content/create.md tutorial page for the How to creat… #6506
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…e your own documentation tutorial chore(scripts): docs:create and docs:edit scripts for content creation and editing Major improvements to docs:create UX for both Claude Code and external tool integration: **New `docs` CLI command:** - Add scripts/docs-cli.js - main CLI with subcommand routing - Add bin field to package.json for `docs` command - Usage: `docs create` and `docs edit` (cleaner than yarn commands) **Smart piping detection:** - Auto-detect when stdout is piped (\!process.stdout.isTTY) - When piping: automatically output prompt text (no flag needed) - When interactive: output prompt file path - --print-prompt flag now optional (auto-enabled when piping) **Specify products:** - simplify link following behavior - treat relative paths as local files, all HTTP/HTTPS as external - stdin now requires --products flag with product keys - --products now accepts keys from products.yml (influxdb3_core, telegraf, etc.) Examples: --products influxdb3_core --products influxdb3_core,influxdb3_enterprise --products telegraf **Usage examples:** # Inside Claude Code - automatic execution docs create drafts/new-feature.md # Pipe to external AI - prompt auto-detected docs create FILE --products X | claude -p docs create FILE --products X | copilot -p # Pipe from stdin echo 'content' | docs create --products X | claude -p Benefits: - Cleaner syntax (no yarn --silent needed) - No manual --print-prompt flag when piping - Consistent with industry tools (git, npm, etc.) - Backward compatible with yarn commands WIP: docs:create usage examples - Redesign of the docs CLI tools for creating and editing content - Cleaner interface works better for piping output to agents and downstream utilities - Updates README.md and other authoring docs This repository includes a `docs` CLI tool for common documentation workflows: ```sh npx docs create drafts/new-feature.md --products influxdb3_core npx docs edit https://docs.influxdata.com/influxdb3/core/admin/ npx docs placeholders content/influxdb3/core/admin/upgrade.md npx docs --help ``` **Run test cases:** ```sh npx docs test ```
jstirnaman
commented
Nov 1, 2025
jstirnaman
changed the title
sanderson
approved these changes
Nov 3, 2025
| #### Include specific files from the same directory | ||
|
|
||
| > [!Caution] | ||
| > \[!Caution] |
There was a problem hiding this comment.
Does this need to be escaped?
| - Avoid: "your token", "the token", "an authorization token" | ||
| 3. **Database names**: | ||
| - Recommended: "the name of the database to [action]" | ||
| - Recommended: "the name of the database to \[action]" |
There was a problem hiding this comment.
This shouldn't need escaping.
There was a problem hiding this comment.
This shouldn't need escaping.
The GitHub format linter escapes them to prevent interpretation as duplicate links that don't have a defined target URL. To prevent the escaping in content files, I had to remove the linter altogether - couldn't configure the behavior.
| _The `placeholders` attribute supercedes the deprecated `code-placeholders` shortcode._ | ||
| *The `placeholders` attribute supercedes the deprecated `code-placeholders` shortcode.* | ||
|
|
||
| #### Automated placeholder syntax |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
…e your own documentation tutorial
Improvements to docs CLI UX for both Claude Code and external tool integration:
New
docsCLI command:docscommanddocs createanddocs edit(cleaner than yarn commands)Smart piping detection:
Auto-detect when stdout is piped (!process.stdout.isTTY)
When piping: automatically output prompt text (no flag needed)
When interactive: output prompt file path
--print-prompt flag now optional (auto-enabled when piping)
Redesign of the docs CLI tools for creating and editing content
Cleaner interface works better for piping output to agents and downstream utilities
Updates README.md and other authoring docs
This repository includes a
docsCLI tool for common documentation workflows:Specify products:
Examples:
Run test cases:
npx docs test