docs: improve marketing positioning for ubiquity

README.md

@@ -1,3 +1,9 @@
+<div align="center">
+
+<img src=".github/hero.png" alt="GitHub Action README Generator" width="800" />
+
+</div>
+
 <div align="center" >
 <!-- start title -->
 
@@ -14,15 +20,43 @@
 </div>
 <!-- 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. Sensible defaults, highly configurable.
 
 <!-- end description -->
 
-📓 Keep your action's README.md up to date with the `title` and `description` from the [`action.yml`](./action.yml) file, while also automatically generating sections for the inputs, outputs, and a usage example for the action. Additionally the Action's usage example is updated to match the Action's current release.
+## Quick Start
+
+```sh
+npx github-action-readme-generator
+```
+
+That's it. Run this in your GitHub Action repository and your README.md is updated.
+
+## Features
+
+|                    | 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                  |
+| :white_check_mark: | **Auto-Versioning** | Updates `uses: owner/repo@v1.2.3` on every release           |
+| :white_check_mark: | **GitHub Badges**   | Adds release, commit, issues, and download badges            |
+| :white_check_mark: | **SVG Branding**    | Generates icon from action.yml branding (100+ icons)         |
+| :white_check_mark: | **Easy Setup**      | Add section markers to README, configure via `.ghadocs.json` |
+| :white_check_mark: | **Dual Mode**       | Use as CLI (`npx`) or GitHub Action in workflows             |
+
+## How It Works
+
+This tool uses markdown comments as section markers in your README:
 
-This is both a CLI tool and GitHub Action that will read the details from a GitHub Action's [`action.yml`](./action.yml) file. Configuration can be provided through a [`.ghadocs.json`](./.ghadocs.json) file stored in the root directory of the Action's repository, via the command line when using the CLI, or through the `with:` section of this Action.
+```markdown
+<!-- start inputs -->
+<!-- end inputs -->
+```
 
-**_HOW_** 📝 This tool uses markdown comments like this `<!-- start section --><!-- stop section -->` as delimiting tokens within your README.md file to determine where to place the generated content. You can find an example README template with all fields filled-in in the [`README.example.md`](./README.example.md) file.\*\*\*
+Run the generator, and content between these markers is automatically updated from your `action.yml`. See [`README.example.md`](./README.example.md) for a complete template.
+
+**Works as both CLI and GitHub Action** - configure via [`.ghadocs.json`](./.ghadocs.json), command line args, or the Action's `with:` section.
 
 ## CLI Usage
 
@@ -120,14 +154,30 @@ This configuration will automatically regenerate your README whenever `action.ym
 ```
 
 <!-- start contents -->
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Features](#features)
+- [How It Works](#how-it-works)
+- [CLI Usage](#cli-usage)
+  - [Stand Alone Usage - if you have a Docker Action](#stand-alone-usage-if-you-have-a-docker-action)
+  - [Install with Yarn or NPM as a dev dependency](#install-with-yarn-or-npm-as-a-dev-dependency)
+  - [Add a script to your project file](#add-a-script-to-your-project-file)
+  - [Using as a Pre-commit Hook](#using-as-a-pre-commit-hook)
+- [Configuration](#configuration)
+  - [Example `.ghadocs.json` with all possible values](#example-ghadocsjson-with-all-possible-values)
+- [Usage](#usage)
+- [Inputs](#inputs)
+
 <!-- end contents -->
 
 ## Usage
 
 <!-- start usage -->
 
 ```yaml
-- uses: bitflight-devops/github-action-readme-generator@v1.8.9
+- uses: bitflight-devops/github-action-readme-generator@v1.8.10
   with:
     # Description: The absolute or relative path to the `action.yml` file to read in
     # from.
@@ -260,3 +310,13 @@ This configuration will automatically regenerate your README whenever `action.ym
 
 <!-- start [.github/ghadocs/examples/] -->
 <!-- end [.github/ghadocs/examples/] -->
+
+---
+
+<div align="center">
+
+<img src=".github/bitflight-devops.png" alt="Bitflight DevOps" width="400" />
+
+**Built by [Bitflight DevOps](https://github.com/bitflight-devops)**
+
+</div>

action.yml

@@ -1,7 +1,7 @@
 ---
 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. Sensible defaults, highly configurable.
 
 branding:
   icon: book-open

package.json

@@ -2,17 +2,20 @@
   "name": "github-action-readme-generator",
   "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. Works as CLI or GitHub Action.",
   "keywords": [
+    "github-actions",
     "actions",
-    "github",
-    "node20",
     "documentation",
-    "github-actions",
-    "generator",
     "readme-generator",
-    "action-metadata",
-    "markdown-generator"
+    "action-yml",
+    "markdown-generator",
+    "github-action-docs",
+    "auto-docs",
+    "devops",
+    "cli",
+    "inputs-outputs",
+    "usage-generator"
   ],
   "homepage": "https://github.com/bitflight-devops/github-action-readme-generator#readme",
   "bugs": {

src/readme-editor.ts

@@ -52,6 +52,14 @@ export default class ReadmeEditor {
     }
   }
 
+  /**
+   * Gets the current README content.
+   * @returns {string} - The README file content.
+   */
+  getReadmeContent(): string {
+    return this.fileContent;
+  }
+
   /**
    * Gets the indexes of the start and end tokens for a given section.
    * @param {string} token - The section token.

src/sections/index.ts

@@ -11,6 +11,7 @@ import type Inputs from '../inputs.js';
 import LogTask from '../logtask/index.js';
 import updateBadges from './update-badges.js';
 import updateBranding from './update-branding.js';
+import updateContents from './update-contents.js';
 import updateDescription from './update-description.js';
 import updateInputs from './update-inputs.js';
 import updateOutputs from './update-outputs.js';
@@ -52,6 +53,9 @@ export default async function updateSection(
     case 'outputs': {
       return updateOutputs(section, inputs);
     }
+    case 'contents': {
+      return updateContents(section, inputs);
+    }
     default: {
       log.debug(`unknown section found <!-- start ${section} -->. No updates were made.`);
       return {};

src/sections/update-contents.ts

@@ -0,0 +1,113 @@
+/**
+ * This TypeScript code exports a function named 'updateContents' which generates
+ * a table of contents from the README.md headers.
+ * @param {ReadmeSection} sectionToken - The sectionToken representing the section of the README to update.
+ * @param {Inputs} inputs - The Inputs class instance.
+ */
+import { ReadmeSection } from '../constants.js';
+import type Inputs from '../inputs.js';
+import LogTask from '../logtask/index.js';
+
+/**
+ * Converts a header text to a GitHub-compatible anchor link.
+ * @param {string} text - The header text to convert.
+ * @returns {string} The anchor link.
+ */
+function headerToAnchor(text: string): string {
+  return text
+    .toLowerCase()
+    .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
+}
+
+/**
+ * Extracts headers from markdown content, excluding those in code blocks.
+ * @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 }> {
+  const headers: Array<{ level: number; text: string }> = [];
+  const lines = content.split('\n');
+  let inCodeBlock = false;
+
+  for (const line of lines) {
+    // Track code block state
+    if (line.trim().startsWith('```')) {
+      inCodeBlock = !inCodeBlock;
+      continue;
+    }
+
+    // Skip if inside code block
+    if (inCodeBlock) {
+      continue;
+    }
+
+    // Match markdown headers (## Header)
+    const headerMatch = /^(#{2,6})\s+(.+)$/.exec(line);
+    if (headerMatch) {
+      const level = headerMatch[1].length;
+      let text = headerMatch[2].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');
+
+      if (text) {
+        headers.push({ level, text });
+      }
+    }
+  }
+
+  return headers;
+}
+
+export default function updateContents(
+  sectionToken: ReadmeSection,
+  inputs: Inputs,
+): Record<string, string> {
+  const log = new LogTask(sectionToken);
+  log.start();
+
+  const content: string[] = [];
+  const readmeContent = inputs.readmeEditor.getReadmeContent();
+
+  // Extract headers from README
+  const headers = extractHeaders(readmeContent);
+
+  // Filter out the title (h1) and contents section itself
+  const tocHeaders = headers.filter(
+    (h) => h.level >= 2 && !h.text.toLowerCase().includes('contents'),
+  );
+
+  if (tocHeaders.length === 0) {
+    log.info('No headers found for table of contents');
+    const ret: Record<string, string> = {};
+    ret[sectionToken] = '';
+    return ret;
+  }
+
+  log.info(`Generating table of contents with ${tocHeaders.length} entries`);
+
+  // Find minimum header level for proper indentation
+  const minLevel = Math.min(...tocHeaders.map((h) => h.level));
+
+  // 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})`);
+  }
+
+  inputs.readmeEditor.updateSection(sectionToken, content);
+  log.success();
+
+  const ret: Record<string, string> = {};
+  ret[sectionToken] = content.join('\n');
+  return ret;
+}