docs: improve marketing positioning for ubiquity #465
Conversation
- Update tagline: "The docs generator for GitHub Actions" - Add Quick Start section with prominent one-liner - Add Features table highlighting 8 key capabilities - Improve package.json keywords for discoverability - Rewrite description to emphasize zero-config and dual-mode https://claude.ai/code/session_018ofWYyu8DZbrnGzaUgWMEd
|
Caution Review failedThe pull request is closed. WalkthroughAdds a comprehensive README rewrite and package/action metadata edits, exposes an in-memory README accessor, and implements a new Table of Contents generator plus routing to invoke it. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant CLI as CLI / Action Trigger
participant ReadmeEditor as ReadmeEditor
participant TOC as updateContents
participant Logger as LogTask
CLI->>ReadmeEditor: getReadmeContent()
ReadmeEditor-->>CLI: return README content
CLI->>TOC: invoke updateContents(sectionToken, inputs)
TOC->>Logger: log start
TOC->>ReadmeEditor: parse content (extract headers)
TOC-->>TOC: normalize headers -> anchors, build TOC markdown
TOC->>Logger: log info / success
TOC->>ReadmeEditor: updateSection('contents', generatedTOC)
ReadmeEditor-->>TOC: acknowledge update
TOC-->>CLI: return generated content record
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes 🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Coverage Report
File Coverage
|
||||||||||||||||||||||||||||||||||||||||||||||||||
There was a problem hiding this comment.
Pull request overview
Updates the project’s public-facing messaging to better position it as a zero-config documentation generator for GitHub Actions and improve npm discoverability.
Changes:
- Refresh marketing copy/tagline across
README.md,action.yml, andpackage.json. - Add a prominent Quick Start section and a features table to the README.
- Update npm
keywordsto improve search/discoverability.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| package.json | Updates package description and expands keywords for discoverability. |
| action.yml | Updates the Action’s Marketplace description/tagline. |
| README.md | Adds Quick Start + Features section and refreshes top-level description copy. |
package.json
Outdated
| "displayName": "bitflight-devops/github-action-readme-generator", | ||
| "version": "1.8.10", | ||
| "description": "This is a CLI tool and GitHub Action that reads in the details from a \nGitHub Action's `action.yml` file and updates the `README.md` file\nwith the `name`, `description`, `usage`, `inputs`, `outputs`, and\nexamples of the action.\nConfiguration can be provided via a `.ghadocs.json` file stored in the\nroot directory of the Action's repository, via the command line when\nusing the cli, or via the `with:` section of this Action.\n\n\nThis tool uses markdown comments as delimiting tokens within the `README.md`\nfile to determine where to place the generated content.\n\n[`README.example.md`](README.example.md) example with all fields filled in, and no other free-form content.", | ||
| "description": "The docs generator for GitHub Actions. Auto-syncs action.yml to README.md with 8 sections: inputs, outputs, usage, badges, branding & more. One command, zero config. Works as CLI or GitHub Action.", |
There was a problem hiding this comment.
The description claims the tool updates "8 sections", but the generator currently only updates 7 sections (title, branding, description, usage, inputs, outputs, badges). contents is included in README_SECTIONS (src/constants.ts) but has no updater in src/sections/index.ts and is skipped as an unknown section, so this statement is inaccurate. Consider either implementing a contents section updater or adjusting the copy to avoid/adjust the section count.
| "description": "The docs generator for GitHub Actions. Auto-syncs action.yml to README.md with 8 sections: inputs, outputs, usage, badges, branding & more. One command, zero config. Works as CLI or GitHub Action.", | |
| "description": "The docs generator for GitHub Actions. Auto-syncs action.yml to README.md with rich sections for inputs, outputs, usage, badges, branding & more. One command, zero config. Works as CLI or GitHub Action.", |
action.yml
Outdated
| name: GitHub Action's Readme Generator | ||
| author: Jamie Nelson <jamie@bitflight.io> | ||
| description: 📓 Effortlessly sync action.yml to README.md. Auto-generates inputs, outputs & usage docs, ensuring docs match code. | ||
| description: 📓 The docs generator for GitHub Actions. Auto-syncs action.yml → README.md with 8 sections including inputs, outputs, usage, badges & branding. One command, zero config. |
There was a problem hiding this comment.
This description says the generator updates "8 sections". In the current implementation, contents is listed as a section (src/constants.ts) but there is no handler for it in src/sections/index.ts, so only 7 sections are actually updated. Please either add support for a contents updater or change the description to avoid stating an incorrect section count.
| description: 📓 The docs generator for GitHub Actions. Auto-syncs action.yml → README.md with 8 sections including inputs, outputs, usage, badges & branding. One command, zero config. | |
| description: 📓 The docs generator for GitHub Actions. Auto-syncs action.yml → README.md with sections including inputs, outputs, usage, badges & branding. One command, zero config. |
README.md
Outdated
| <!-- start description --> | ||
|
|
||
| 📓 Effortlessly sync action.yml to README.md. Auto-generates inputs, outputs & usage docs, ensuring docs match code. | ||
| 📓 The docs generator for GitHub Actions. Auto-syncs action.yml → README.md with 8 sections including inputs, outputs, usage, badges & branding. One command, zero config. |
There was a problem hiding this comment.
The README description states the tool updates "8 sections". The code currently updates 7 sections; contents is present in README_SECTIONS but has no updater (see src/sections/index.ts), so it is skipped. Please adjust the wording (e.g., remove the explicit count) or implement contents generation so the claim matches behavior.
| 📓 The docs generator for GitHub Actions. Auto-syncs action.yml → README.md with 8 sections including inputs, outputs, usage, badges & branding. One command, zero config. | |
| 📓 The docs generator for GitHub Actions. Auto-syncs action.yml → README.md with key sections including inputs, outputs, usage, badges & branding. One command, zero config. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@README.md`:
- Around line 31-35: The Features table in README.md uses lowercase "markdown"
in the Description cells; update each occurrence to capitalize the proper noun
"Markdown" (e.g., change "Auto-generates markdown table from `action.yml`
inputs" to "Auto-generates Markdown table from `action.yml` inputs", and
similarly for the outputs row) so the table entries for "Inputs Table", "Outputs
Table", and "Usage Example" use "Markdown" consistently.
README.md
Outdated
| | | Feature | Description | | ||
| | :----------------: | ------------------- | ------------------------------------------------------- | | ||
| | :white_check_mark: | **Inputs Table** | Auto-generates markdown table from `action.yml` inputs | | ||
| | :white_check_mark: | **Outputs Table** | Auto-generates markdown table from `action.yml` outputs | | ||
| | :white_check_mark: | **Usage Example** | Creates ready-to-copy YAML workflow snippet | |
There was a problem hiding this comment.
Capitalize “Markdown” in the Features table.
LanguageTool flagged the proper noun usage.
📝 Proposed fix
-| :white_check_mark: | **Inputs Table** | Auto-generates markdown table from `action.yml` inputs |
-| :white_check_mark: | **Outputs Table** | Auto-generates markdown table from `action.yml` outputs |
+| :white_check_mark: | **Inputs Table** | Auto-generates Markdown table from `action.yml` inputs |
+| :white_check_mark: | **Outputs Table** | Auto-generates Markdown table from `action.yml` outputs |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | | Feature | Description | | |
| | :----------------: | ------------------- | ------------------------------------------------------- | | |
| | :white_check_mark: | **Inputs Table** | Auto-generates markdown table from `action.yml` inputs | | |
| | :white_check_mark: | **Outputs Table** | Auto-generates markdown table from `action.yml` outputs | | |
| | :white_check_mark: | **Usage Example** | Creates ready-to-copy YAML workflow snippet | | |
| | | Feature | Description | | |
| | :----------------: | ------------------- | ------------------------------------------------------- | | |
| | :white_check_mark: | **Inputs Table** | Auto-generates Markdown table from `action.yml` inputs | | |
| | :white_check_mark: | **Outputs Table** | Auto-generates Markdown table from `action.yml` outputs | | |
| | :white_check_mark: | **Usage Example** | Creates ready-to-copy YAML workflow snippet | |
🧰 Tools
🪛 LanguageTool
[uncategorized] ~33-~33: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ... | Inputs Table | Auto-generates markdown table from action.yml inputs | | :wh...
(MARKDOWN_NNP)
[uncategorized] ~34-~34: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ... | Outputs Table | Auto-generates markdown table from action.yml outputs | | :wh...
(MARKDOWN_NNP)
🤖 Prompt for AI Agents
In `@README.md` around lines 31 - 35, The Features table in README.md uses
lowercase "markdown" in the Description cells; update each occurrence to
capitalize the proper noun "Markdown" (e.g., change "Auto-generates markdown
table from `action.yml` inputs" to "Auto-generates Markdown table from
`action.yml` inputs", and similarly for the outputs row) so the table entries
for "Inputs Table", "Outputs Table", and "Usage Example" use "Markdown"
consistently.
- Add update-contents.ts to generate TOC from README headers - Add getReadmeContent() method to ReadmeEditor class - Wire up contents case in sections/index.ts switch statement - The "8 sections" claim is now accurate (was 7 before) https://claude.ai/code/session_018ofWYyu8DZbrnGzaUgWMEd
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| function headerToAnchor(text: string): string { | ||
| return text | ||
| .toLowerCase() | ||
| .replace(/[^\w\s-]/g, '') // Remove special characters except hyphens |
There was a problem hiding this comment.
🚫 [eslint] <unicorn/prefer-string-replace-all> reported by reviewdog 🐶
Prefer String#replaceAll() over String#replace().
| .replace(/[^\w\s-]/g, '') // Remove special characters except hyphens | |
| .replaceAll(/[^\w\s-]/g, '') // Remove special characters except hyphens |
| return text | ||
| .toLowerCase() | ||
| .replace(/[^\w\s-]/g, '') // Remove special characters except hyphens | ||
| .replace(/\s+/g, '-') // Replace spaces with hyphens |
There was a problem hiding this comment.
🚫 [eslint] <unicorn/prefer-string-replace-all> reported by reviewdog 🐶
Prefer String#replaceAll() over String#replace().
| .replace(/\s+/g, '-') // Replace spaces with hyphens | |
| .replaceAll(/\s+/g, '-') // Replace spaces with hyphens |
| .toLowerCase() | ||
| .replace(/[^\w\s-]/g, '') // Remove special characters except hyphens | ||
| .replace(/\s+/g, '-') // Replace spaces with hyphens | ||
| .replace(/-+/g, '-') // Collapse multiple hyphens |
There was a problem hiding this comment.
🚫 [eslint] <unicorn/prefer-string-replace-all> reported by reviewdog 🐶
Prefer String#replaceAll() over String#replace().
| .replace(/-+/g, '-') // Collapse multiple hyphens | |
| .replaceAll(/-+/g, '-') // Collapse multiple hyphens |
| .replace(/[^\w\s-]/g, '') // Remove special characters except hyphens | ||
| .replace(/\s+/g, '-') // Replace spaces with hyphens | ||
| .replace(/-+/g, '-') // Collapse multiple hyphens | ||
| .replace(/^-|-$/g, ''); // Remove leading/trailing hyphens |
There was a problem hiding this comment.
🚫 [eslint] <unicorn/prefer-string-replace-all> reported by reviewdog 🐶
Prefer String#replaceAll() over String#replace().
| .replace(/^-|-$/g, ''); // Remove leading/trailing hyphens | |
| .replaceAll(/^-|-$/g, ''); // Remove leading/trailing hyphens |
| * @param {string} content - The markdown content. | ||
| * @returns {Array<{level: number, text: string}>} Array of header objects. | ||
| */ | ||
| function extractHeaders(content: string): Array<{ level: number; text: string }> { |
There was a problem hiding this comment.
🚫 [eslint] <@typescript-eslint/array-type> reported by reviewdog 🐶
Array type using 'Array' is forbidden. Use 'T[]' instead.
| function extractHeaders(content: string): Array<{ level: number; text: string }> { | |
| function extractHeaders(content: string): { level: number; text: string }[] { |
| * @returns {Array<{level: number, text: string}>} Array of header objects. | ||
| */ | ||
| function extractHeaders(content: string): Array<{ level: number; text: string }> { | ||
| const headers: Array<{ level: number; text: string }> = []; |
There was a problem hiding this comment.
🚫 [eslint] <@typescript-eslint/array-type> reported by reviewdog 🐶
Array type using 'Array' is forbidden. Use 'T[]' instead.
| const headers: Array<{ level: number; text: string }> = []; | |
| const headers: { level: number; text: string }[] = []; |
| let text = headerMatch[2].trim(); | ||
|
|
||
| // Remove inline images and other markdown formatting from header text | ||
| text = text.replace(/<img[^>]*>/g, '').trim(); |
There was a problem hiding this comment.
🚫 [eslint] <unicorn/prefer-string-replace-all> reported by reviewdog 🐶
Prefer String#replaceAll() over String#replace().
| text = text.replace(/<img[^>]*>/g, '').trim(); | |
| text = text.replaceAll(/<img[^>]*>/g, '').trim(); |
| // Remove inline images and other markdown formatting from header text | ||
| text = text.replace(/<img[^>]*>/g, '').trim(); | ||
| // Remove markdown links but keep the text | ||
| text = text.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1'); |
There was a problem hiding this comment.
🚫 [eslint] <unicorn/prefer-string-replace-all> reported by reviewdog 🐶
Prefer String#replaceAll() over String#replace().
| text = text.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1'); | |
| text = text.replaceAll(/\[([^\]]+)\]\([^)]+\)/g, '$1'); |
| // Remove inline images and other markdown formatting from header text | ||
| text = text.replace(/<img[^>]*>/g, '').trim(); | ||
| // Remove markdown links but keep the text | ||
| text = text.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1'); |
There was a problem hiding this comment.
/[([^\]]+)]([^)]+)/g can be optimized to /[([^\]]+)]([^)]+)/g
| text = text.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1'); | |
| text = text.replace(/\[([^\]]+)]\([^)]+\)/g, '$1'); |
| content.push('## Table of Contents'); | ||
| content.push(''); |
There was a problem hiding this comment.
🚫 [eslint] <unicorn/prefer-single-call> reported by reviewdog 🐶
Do not call Array#push() multiple times.
| content.push('## Table of Contents'); | |
| content.push(''); | |
| content.push('## Table of Contents', ''); |
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In `@src/sections/update-contents.ts`:
- Around line 97-105: The TOC generation must disambiguate duplicate anchors
like GitHub; update the loop that builds anchors for tocHeaders to track
occurrences (e.g., a Map keyed by the base anchor from headerToAnchor) and for
each header compute base = headerToAnchor(header.text), increment its count, and
if count > 1 append a numeric suffix of `-${count - 1}` to the anchor so
subsequent duplicates become anchor-1, anchor-2, etc., then push the TOC line
using that unique anchor; apply this logic where tocHeaders, headerToAnchor,
minLevel and content are used to build the TOC.
- Around line 85-90: The function currently returns early when tocHeaders.length
=== 0 which leaves the README's TOC unchanged; instead, set ret[sectionToken] =
'' and do not return early—allow the function to follow the same code path that
writes/updates sections to the README (i.e., use the existing README
update/write logic used when headers exist) so the empty TOC is persisted;
remove the early return and ensure the existing write/update call is invoked
with the ret map so the stale TOC is cleared.
| if (tocHeaders.length === 0) { | ||
| log.info('No headers found for table of contents'); | ||
| const ret: Record<string, string> = {}; | ||
| ret[sectionToken] = ''; | ||
| return ret; | ||
| } |
There was a problem hiding this comment.
Clear the TOC section when no headers are found.
Right now you return early without updating the README, which leaves stale TOC content in place.
🐛 Proposed fix
if (tocHeaders.length === 0) {
log.info('No headers found for table of contents');
+ inputs.readmeEditor.updateSection(sectionToken, '');
const ret: Record<string, string> = {};
ret[sectionToken] = '';
return ret;
}🤖 Prompt for AI Agents
In `@src/sections/update-contents.ts` around lines 85 - 90, The function currently
returns early when tocHeaders.length === 0 which leaves the README's TOC
unchanged; instead, set ret[sectionToken] = '' and do not return early—allow the
function to follow the same code path that writes/updates sections to the README
(i.e., use the existing README update/write logic used when headers exist) so
the empty TOC is persisted; remove the early return and ensure the existing
write/update call is invoked with the ret map so the stale TOC is cleared.
| // Generate TOC entries | ||
| content.push('## Table of Contents'); | ||
| content.push(''); | ||
|
|
||
| for (const header of tocHeaders) { | ||
| const indent = ' '.repeat(header.level - minLevel); | ||
| const anchor = headerToAnchor(header.text); | ||
| content.push(`${indent}- [${header.text}](#${anchor})`); | ||
| } |
There was a problem hiding this comment.
Handle duplicate headings to avoid broken TOC links.
GitHub disambiguates duplicate anchors with numeric suffixes; current logic produces duplicate anchors.
🐛 Proposed fix
// Generate TOC entries
content.push('## Table of Contents');
content.push('');
+ const slugCounts = new Map<string, number>();
for (const header of tocHeaders) {
const indent = ' '.repeat(header.level - minLevel);
- const anchor = headerToAnchor(header.text);
- content.push(`${indent}- [${header.text}](#${anchor})`);
+ const baseAnchor = headerToAnchor(header.text);
+ const count = slugCounts.get(baseAnchor) ?? 0;
+ slugCounts.set(baseAnchor, count + 1);
+ const anchor = count === 0 ? baseAnchor : `${baseAnchor}-${count}`;
+ content.push(`${indent}- [${header.text}](#${anchor})`);
}🤖 Prompt for AI Agents
In `@src/sections/update-contents.ts` around lines 97 - 105, The TOC generation
must disambiguate duplicate anchors like GitHub; update the loop that builds
anchors for tocHeaders to track occurrences (e.g., a Map keyed by the base
anchor from headerToAnchor) and for each header compute base =
headerToAnchor(header.text), increment its count, and if count > 1 append a
numeric suffix of `-${count - 1}` to the anchor so subsequent duplicates become
anchor-1, anchor-2, etc., then push the TOC line using that unique anchor; apply
this logic where tocHeaders, headerToAnchor, minLevel and content are used to
build the TOC.
- Add hero.png at top of README (optimized from 951KB to 907KB) - Add bitflight-devops.png at bottom (optimized from 4.1MB to 958KB) - Rename images from IMG_9050/IMG_9051 to descriptive names - Total image size reduced from 5MB to 1.9MB https://claude.ai/code/session_018ofWYyu8DZbrnGzaUgWMEd
- Replace "zero config" with "sensible defaults, highly configurable" - Update Features table: "Zero Config" → "Easy Setup" - Remove "zero-config" from package.json keywords - Accurate: users need to add section markers and can configure via .ghadocs.json https://claude.ai/code/session_018ofWYyu8DZbrnGzaUgWMEd
https://claude.ai/code/session_018ofWYyu8DZbrnGzaUgWMEd
Summary by CodeRabbit
Documentation
New Features
✏️ Tip: You can customize this high-level summary in your review settings.