github-action-readme-generator 1.12.9 → 2.0.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [2.0.0](https://github.com/bitflight-devops/github-action-readme-generator/compare/v1.12.9...v2.0.0) (2026-09-25)
+
+### ⚠ BREAKING CHANGES
+
+* **prettier:** format only the spans between section markers (#690)
+
+### Bug Fixes
+
+* **prettier:** format only the spans between section markers ([#690](https://github.com/bitflight-devops/github-action-readme-generator/issues/690)) ([f48b40d](https://github.com/bitflight-devops/github-action-readme-generator/commit/f48b40d7f03ec632f4c10957c7a2130f2d20cc7f))
+
 ## [1.12.9](https://github.com/bitflight-devops/github-action-readme-generator/compare/v1.12.8...v1.12.9) (2026-09-22)
 
 

package/README.md

@@ -70,11 +70,12 @@ sections whose markers you added are touched.
 **Text outside the markers is yours and stays yours.** The tool replaces only
 the span between a `start`/`end` pair.
 
-**With `pretty` on (the default), the whole file is reformatted.** That is the
-one exception to the rule above: prettier runs over the entire README, so a
-first run on a file that was not already prettier-formatted will also reflow
-prose the tool did not generate. Run with `--pretty=false` if you would rather
-it left your formatting alone.
+**`pretty` formats the generated sections and nothing else.** With it on (the
+default) prettier runs over each replaced span on its own — it pads the tables
+it generated and tidies the usage block, and it never reaches your prose. A
+first run on a file that was not already prettier-formatted changes the marker
+sections and no other line. Run with `--pretty=false` to have the generated
+sections written exactly as the tool composed them.
 
 **Only yaml and markdown code blocks are reformatted; every other fence is left
 as you wrote it.** Formatting needs a prettier plugin per language, and this tool
@@ -105,7 +106,7 @@ apply to the CLI and the Action alike.
 | --paths:readme, --readme                                   | Path to the README file                                                                   | `README.md`                    |
 | --owner                                                    | The GitHub Action repository owner                                                        | autodetected                   |
 | --repo                                                     | The GitHub Action repository name                                                         | autodetected                   |
-| --prettier, --pretty                                       | Format the markdown using prettier formatter                                              | `true`                         |
+| --prettier, --pretty                                       | Format the generated sections using the prettier formatter                                | `true`                         |
 | --versioning:enabled, --versioning                         | Enable the update of the usage version to match the latest version                        | `true`                         |
 | --versioning:source, --version_source                      | How to detect the version: `git-tag`, `git-branch`, `git-sha`, `package-json`, `explicit` | `git-tag`                      |
 | --versioning:override, --version_override, --setversion    | Set a specific version to display in the README.md                                        | unset                          |
@@ -118,7 +119,8 @@ apply to the CLI and the Action alike.
 | --save                                                     | Save this config to `.ghadocs.json`                                                       | `false`                        |
 | --debug_config, --debug_nconf                              | Print out the resolved config with all values, then continue                              | off                            |
 
-To turn formatting off, pass the flag explicitly:
+To write the generated sections exactly as the tool composed them, pass the flag
+explicitly:
 
 ```sh
 npx github-action-readme-generator --pretty=false
@@ -267,7 +269,7 @@ value replaced by `***REDACTED***`. Keys whose names look sensitive (`auth`,
 <!-- start usage -->
 
 ```yaml
-- uses: bitflight-devops/github-action-readme-generator@v1.12.8
+- uses: bitflight-devops/github-action-readme-generator@v1.12.9
   with:
     # Description: The absolute or relative path to the `action.yml` file to read in
     # from.
@@ -297,7 +299,9 @@ value replaced by `***REDACTED***`. Keys whose names look sensitive (`auth`,
     # Default: false
     save: ""
 
-    # Description: Use `prettier` to pretty print the new README.md file
+    # Description: Use `prettier` to pretty print the sections this tool generates.
+    # Only the content between a section's start and end markers is formatted. The
+    # rest of the README.md file is left byte for byte as it was.
     #
     # Default: true
     pretty: ""
@@ -389,7 +393,7 @@ value replaced by `***REDACTED***`. Keys whose names look sensitive (`auth`,
 | <b><code>owner</code></b>                        | The GitHub Action repository owner, this field is autodetected by default.<br />Example: <code>bitflight-devops</code> or <code>your-gh-username</code>                                                                                                                                                                                                                                                                                                                                                                                                                                |                                           | **false**    |
 | <b><code>repo</code></b>                         | The GitHub Action repository name, this field is autodetected by default.<br />Example: <code>github-action-readme-generator</code>                                                                                                                                                                                                                                                                                                                                                                                                                                                    |                                           | **false**    |
 | <b><code>save</code></b>                         | Save the provided values in a <code>.ghadocs.json</code> file.<br />This will update any existing <code>.ghadocs.json</code> file that is in place.                                                                                                                                                                                                                                                                                                                                                                                                                                    | <code>false</code>                        | **false**    |
-| <b><code>pretty</code></b>                       | Use <code>prettier</code> to pretty print the new README.md file                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | <code>true</code>                         | **false**    |
+| <b><code>pretty</code></b>                       | Use <code>prettier</code> to pretty print the sections this tool generates.<br />Only the content between a section's start and end markers is formatted.<br />The rest of the README.md file is left byte for byte as it was.                                                                                                                                                                                                                                                                                                                                                         | <code>true</code>                         | **false**    |
 | <b><code>versioning_enabled</code></b>           | Enable the update of the usage version in the <code>uses:</code> example.<br />The version comes from whichever <code>version_source</code> selects. The default, <code>git-tag</code>, uses the latest git tag, and falls back to <code>package.json</code>, then to <code>$npm_package_version</code>, then to <code>0.0.0</code> when no tag is found — a shallow or tagless checkout takes that path.<br />Output if your action repo is <code>reviewdog/action-eslint</code> and the latest tag is <code>v1.0.1</code>:<br /><code>uses: reviewdog/action-eslint@v1.0.1</code>    | <code>true</code>                         | **false**    |
 | <b><code>version_override</code></b>             | Set a specific version to display in the README.md, maybe you want to use a major or minor version                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |                                           | **false**    |
 | <b><code>version_prefix</code></b>               | Prefix the version with this value, if it isn't already prefixed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | <code>v</code>                            | **false**    |

package/action.yml

@@ -36,7 +36,9 @@ inputs:
     default: false
   pretty:
     description: |
-      Use `prettier` to pretty print the new README.md file
+      Use `prettier` to pretty print the sections this tool generates.
+      Only the content between a section's start and end markers is formatted.
+      The rest of the README.md file is left byte for byte as it was.
     required: false
     default: 'true'
   versioning_enabled:

package/dist/bin/index.js

@@ -18,7 +18,7 @@ import { fileURLToPath } from "node:url";
 import * as child from "child_process";
 import { setTimeout as setTimeout$1 } from "timers";
 import process$1 from "node:process";
-import os$1, { EOL as EOL$1 } from "node:os";
+import os$1 from "node:os";
 import tty from "node:tty";
 import { execFileSync, execSync } from "node:child_process";
 //#region \0rolldown/runtime.js
@@ -67023,14 +67023,51 @@ const startTokenFormat = "(^|[^`\\\\])<!--\\s+start\\s+%s\\s+-->";
 * The format for the end token of a section.
 */
 const endTokenFormat = "(^|[^`\\\\])<!--\\s+end\\s+%s\\s+-->";
+/**
+* Lays out section content the way it sits between its markers.
+* @param {string} content - The trimmed section content.
+* @param {boolean} addNewlines - Whether to pad the content with newlines.
+* @returns {string} - The text that goes between the markers.
+*/
+function layoutSpan(content, addNewlines) {
+	return addNewlines ? `\n\n${content}\n` : content;
+}
+/**
+* True when every line break in `text` is CRLF, and there is at least one.
+*
+* Only a document that is CRLF throughout is edited as CRLF. Removing the `\r`
+* before each `\n` and adding it back is then an exact round trip, so the
+* bytes outside the markers survive. A document that mixes the two is left as
+* it is, since no single ending would reproduce it.
+* @param {string} text - The document.
+* @returns {boolean} - Whether the document uses CRLF line endings.
+*/
+function usesCrlf(text) {
+	return text.includes("\r\n") && !/(^|[^\r])\n/.test(text);
+}
 var ReadmeEditor = class {
 	log = new LogTask("ReadmeEditor");
 	/**
 	* The path to the README file.
 	*/
 	filePath;
+	/**
+	* The document with LF line endings, whatever the file uses. Every edit and
+	* every formatter pass works on LF; `dumpToFile` restores the file's own
+	* ending on the way out.
+	*/
 	fileContent;
 	/**
+	* Whether the file on disk is CRLF throughout — see `usesCrlf`.
+	*/
+	crlf = false;
+	/**
+	* The padded sections this editor has replaced, each against the content it
+	* wrote. `dumpToFile` formats these spans and nothing else — see
+	* `formatUpdatedSections`.
+	*/
+	updatedSections = /* @__PURE__ */ new Map();
+	/**
 	* Creates a new instance of `ReadmeEditor`.
 	* @param {string} filePath - The path to the README file.
 	*/
@@ -67038,15 +67075,17 @@ var ReadmeEditor = class {
 		this.filePath = filePath;
 		try {
 			fs$3.accessSync(filePath);
-			this.fileContent = fs$3.readFileSync(filePath, "utf8");
-			if (process.env.GITHUB_ACTIONS) setOutput("readme_before", this.fileContent);
+			const raw = fs$3.readFileSync(filePath, "utf8");
+			if (process.env.GITHUB_ACTIONS) setOutput("readme_before", raw);
+			this.crlf = usesCrlf(raw);
+			this.fileContent = this.crlf ? raw.replaceAll("\r\n", "\n") : raw;
 		} catch (error) {
 			this.log.fail(`Readme at '${filePath}' does not exist.`);
 			throw error;
 		}
 	}
 	/**
-	* Gets the current README content.
+	* Gets the current README content, with LF line endings.
 	* @returns {string} - The README file content.
 	*/
 	getReadmeContent() {
@@ -67081,24 +67120,66 @@ var ReadmeEditor = class {
 	*/
 	updateSection(name, providedContent, addNewlines = true) {
 		const log = new LogTask(name);
-		const content = (Array.isArray(providedContent) ? providedContent.join(EOL$1) : providedContent ?? "").trim();
+		const content = (Array.isArray(providedContent) ? providedContent.join("\n") : providedContent ?? "").replaceAll("\r\n", "\n").trim();
 		log.info(`Looking for the ${name} token in ${this.filePath}`);
 		const [startIndex, stopIndex] = this.getTokenIndexes(name, log);
 		if (startIndex && stopIndex) {
 			const beforeContent = this.fileContent.slice(0, startIndex);
 			const afterContent = this.fileContent.slice(stopIndex);
-			this.fileContent = addNewlines ? `${beforeContent}\n\n${content}\n${afterContent}` : `${beforeContent}${content}${afterContent}`;
+			this.fileContent = `${beforeContent}${layoutSpan(content, addNewlines)}${afterContent}`;
+			if (addNewlines) this.updatedSections.set(name, content);
 		}
 	}
 	/**
+	* Formats the span of one section in isolation and splices it back.
+	*
+	* The content is formatted on its own and reassembled with the same
+	* surrounding newlines `updateSection` wrote, so the markers and every byte
+	* outside them survive untouched.
+	*
+	* The span is formatted only while its markers still bound exactly the text
+	* `updateSection` wrote. The markers are paired again here, after every
+	* section has been written, and a marker another section wrote can win that
+	* pairing; the text between such a pair is not this tool's to format.
+	* @param {string} name - The name of the section.
+	* @param {string} content - The content `updateSection` wrote, padded.
+	*/
+	async formatSection(name, content) {
+		const [startIndex, stopIndex] = this.getTokenIndexes(name);
+		if (!startIndex || !stopIndex) return;
+		if (startIndex > stopIndex || this.fileContent.slice(startIndex, stopIndex) !== layoutSpan(content, true)) {
+			this.log.warn(`The '${name}' markers no longer bound the text written to them. Leaving the section unformatted`);
+			return;
+		}
+		const formatted = content === "" ? "" : (await formatMarkdown(content)).trim();
+		const span = formatted === "" ? "\n" : layoutSpan(formatted, true);
+		this.fileContent = `${this.fileContent.slice(0, startIndex)}${span}${this.fileContent.slice(stopIndex)}`;
+	}
+	/**
+	* Formats every span this editor replaced, one span at a time.
+	*
+	* Each span is located again before it is formatted, because formatting the
+	* previous one moves the indexes of the spans after it. A formatted span no
+	* longer holds the text `updateSection` wrote, so it is forgotten once
+	* formatted.
+	* @returns {Promise<void>}
+	*/
+	async formatUpdatedSections() {
+		for (const [name, content] of this.updatedSections) await this.formatSection(name, content);
+		this.updatedSections.clear();
+	}
+	/**
 	* Dumps the modified content back to the README file.
-	* @param {boolean} [prettier=true] - Run the result through prettier before
-	*   writing. Callers pass the resolved `pretty` input; it defaults to true so
-	*   constructing a ReadmeEditor directly keeps the formatting behaviour.
+	* @param {boolean} [prettier=true] - Run the replaced spans through prettier
+	*   before writing. Callers pass the resolved `pretty` input; it defaults to
+	*   true so constructing a ReadmeEditor directly keeps the formatting
+	*   behaviour. Text outside the markers is never formatted, whatever this
+	*   flag says — see `docs/tool-contract.md`.
 	* @returns {Promise<void>}
 	*/
 	async dumpToFile(prettier = true) {
-		const content = prettier ? await formatMarkdown(this.fileContent) : this.fileContent;
+		if (prettier) await this.formatUpdatedSections();
+		const content = this.crlf ? this.fileContent.replaceAll("\n", "\r\n") : this.fileContent;
 		if (process.env.GITHUB_ACTIONS) setOutput("readme_after", content);
 		return fs$3.promises.writeFile(this.filePath, content, "utf8");
 	}

package/dist/mjs/index.js

@@ -10,7 +10,6 @@ import * as feather from "feather-icons";
 import { icons } from "feather-icons";
 import chalkPkg from "chalk";
 import { execFileSync, execSync } from "node:child_process";
-import { EOL } from "node:os";
 import * as markdown from "prettier/plugins/markdown";
 import * as yaml from "prettier/plugins/yaml";
 import { format } from "prettier/standalone";
@@ -860,14 +859,51 @@ const startTokenFormat = "(^|[^`\\\\])<!--\\s+start\\s+%s\\s+-->";
 * The format for the end token of a section.
 */
 const endTokenFormat = "(^|[^`\\\\])<!--\\s+end\\s+%s\\s+-->";
+/**
+* Lays out section content the way it sits between its markers.
+* @param {string} content - The trimmed section content.
+* @param {boolean} addNewlines - Whether to pad the content with newlines.
+* @returns {string} - The text that goes between the markers.
+*/
+function layoutSpan(content, addNewlines) {
+	return addNewlines ? `\n\n${content}\n` : content;
+}
+/**
+* True when every line break in `text` is CRLF, and there is at least one.
+*
+* Only a document that is CRLF throughout is edited as CRLF. Removing the `\r`
+* before each `\n` and adding it back is then an exact round trip, so the
+* bytes outside the markers survive. A document that mixes the two is left as
+* it is, since no single ending would reproduce it.
+* @param {string} text - The document.
+* @returns {boolean} - Whether the document uses CRLF line endings.
+*/
+function usesCrlf(text) {
+	return text.includes("\r\n") && !/(^|[^\r])\n/.test(text);
+}
 var ReadmeEditor = class {
 	log = new LogTask("ReadmeEditor");
 	/**
 	* The path to the README file.
 	*/
 	filePath;
+	/**
+	* The document with LF line endings, whatever the file uses. Every edit and
+	* every formatter pass works on LF; `dumpToFile` restores the file's own
+	* ending on the way out.
+	*/
 	fileContent;
 	/**
+	* Whether the file on disk is CRLF throughout — see `usesCrlf`.
+	*/
+	crlf = false;
+	/**
+	* The padded sections this editor has replaced, each against the content it
+	* wrote. `dumpToFile` formats these spans and nothing else — see
+	* `formatUpdatedSections`.
+	*/
+	updatedSections = /* @__PURE__ */ new Map();
+	/**
 	* Creates a new instance of `ReadmeEditor`.
 	* @param {string} filePath - The path to the README file.
 	*/
@@ -875,15 +911,17 @@ var ReadmeEditor = class {
 		this.filePath = filePath;
 		try {
 			fs.accessSync(filePath);
-			this.fileContent = fs.readFileSync(filePath, "utf8");
-			if (process.env.GITHUB_ACTIONS) core.setOutput("readme_before", this.fileContent);
+			const raw = fs.readFileSync(filePath, "utf8");
+			if (process.env.GITHUB_ACTIONS) core.setOutput("readme_before", raw);
+			this.crlf = usesCrlf(raw);
+			this.fileContent = this.crlf ? raw.replaceAll("\r\n", "\n") : raw;
 		} catch (error) {
 			this.log.fail(`Readme at '${filePath}' does not exist.`);
 			throw error;
 		}
 	}
 	/**
-	* Gets the current README content.
+	* Gets the current README content, with LF line endings.
 	* @returns {string} - The README file content.
 	*/
 	getReadmeContent() {
@@ -918,24 +956,66 @@ var ReadmeEditor = class {
 	*/
 	updateSection(name, providedContent, addNewlines = true) {
 		const log = new LogTask(name);
-		const content = (Array.isArray(providedContent) ? providedContent.join(EOL) : providedContent ?? "").trim();
+		const content = (Array.isArray(providedContent) ? providedContent.join("\n") : providedContent ?? "").replaceAll("\r\n", "\n").trim();
 		log.info(`Looking for the ${name} token in ${this.filePath}`);
 		const [startIndex, stopIndex] = this.getTokenIndexes(name, log);
 		if (startIndex && stopIndex) {
 			const beforeContent = this.fileContent.slice(0, startIndex);
 			const afterContent = this.fileContent.slice(stopIndex);
-			this.fileContent = addNewlines ? `${beforeContent}\n\n${content}\n${afterContent}` : `${beforeContent}${content}${afterContent}`;
+			this.fileContent = `${beforeContent}${layoutSpan(content, addNewlines)}${afterContent}`;
+			if (addNewlines) this.updatedSections.set(name, content);
 		}
 	}
 	/**
+	* Formats the span of one section in isolation and splices it back.
+	*
+	* The content is formatted on its own and reassembled with the same
+	* surrounding newlines `updateSection` wrote, so the markers and every byte
+	* outside them survive untouched.
+	*
+	* The span is formatted only while its markers still bound exactly the text
+	* `updateSection` wrote. The markers are paired again here, after every
+	* section has been written, and a marker another section wrote can win that
+	* pairing; the text between such a pair is not this tool's to format.
+	* @param {string} name - The name of the section.
+	* @param {string} content - The content `updateSection` wrote, padded.
+	*/
+	async formatSection(name, content) {
+		const [startIndex, stopIndex] = this.getTokenIndexes(name);
+		if (!startIndex || !stopIndex) return;
+		if (startIndex > stopIndex || this.fileContent.slice(startIndex, stopIndex) !== layoutSpan(content, true)) {
+			this.log.warn(`The '${name}' markers no longer bound the text written to them. Leaving the section unformatted`);
+			return;
+		}
+		const formatted = content === "" ? "" : (await formatMarkdown(content)).trim();
+		const span = formatted === "" ? "\n" : layoutSpan(formatted, true);
+		this.fileContent = `${this.fileContent.slice(0, startIndex)}${span}${this.fileContent.slice(stopIndex)}`;
+	}
+	/**
+	* Formats every span this editor replaced, one span at a time.
+	*
+	* Each span is located again before it is formatted, because formatting the
+	* previous one moves the indexes of the spans after it. A formatted span no
+	* longer holds the text `updateSection` wrote, so it is forgotten once
+	* formatted.
+	* @returns {Promise<void>}
+	*/
+	async formatUpdatedSections() {
+		for (const [name, content] of this.updatedSections) await this.formatSection(name, content);
+		this.updatedSections.clear();
+	}
+	/**
 	* Dumps the modified content back to the README file.
-	* @param {boolean} [prettier=true] - Run the result through prettier before
-	*   writing. Callers pass the resolved `pretty` input; it defaults to true so
-	*   constructing a ReadmeEditor directly keeps the formatting behaviour.
+	* @param {boolean} [prettier=true] - Run the replaced spans through prettier
+	*   before writing. Callers pass the resolved `pretty` input; it defaults to
+	*   true so constructing a ReadmeEditor directly keeps the formatting
+	*   behaviour. Text outside the markers is never formatted, whatever this
+	*   flag says — see `docs/tool-contract.md`.
 	* @returns {Promise<void>}
 	*/
 	async dumpToFile(prettier = true) {
-		const content = prettier ? await formatMarkdown(this.fileContent) : this.fileContent;
+		if (prettier) await this.formatUpdatedSections();
+		const content = this.crlf ? this.fileContent.replaceAll("\n", "\r\n") : this.fileContent;
 		if (process.env.GITHUB_ACTIONS) core.setOutput("readme_after", content);
 		return fs.promises.writeFile(this.filePath, content, "utf8");
 	}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "github-action-readme-generator",
   "displayName": "bitflight-devops/github-action-readme-generator",
-  "version": "1.12.9",
+  "version": "2.0.0",
   "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",
@@ -128,7 +128,7 @@
       "@semantic-release/github",
       "@semantic-release/git"
     ],
-    "preset": "angular"
+    "preset": "conventionalcommits"
   },
   "dependencies": {
     "@actions/core": "^3.0.0",
@@ -156,6 +156,7 @@
     "@vitest/coverage-v8": "4.1.11",
     "@voidzero-dev/vite-plus-core": "0.2.8",
     "commitizen": "^4.3.1",
+    "conventional-changelog-conventionalcommits": "^9.3.1",
     "conventional-commits": "^1.6.0",
     "cz-conventional-changelog": "^3.3.0",
     "dotenv": "^17.2.4",