fix(docs): add overwriteExisting option for flexible README overwrite behaviour #6249
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
… behaviour On the `docs-readme` output target, a new `overwriteExisting` option allows developers to control how existing README files are handled when writing to a custom path. This adds flexibility to either: - Always overwrite the full README (`true`), - Only write the full README if no file exists (`'if-missing'`), or - Preserve existing custom content (**default** `false`). Now, `docs-readme` treats the component `readme.md` files as the canonical source for manually-entered custom content when overwriting READMEs. This ensures that custom content is preserved unless explicitly overwritten. For example, when using the `'if-missing'` flag, a project that writes component readmes into a documentation library folder can maintain consistent, idempotent output across local builds and CI environments. Custom edits to the destination files will be maintained, while files without customisation will be fully exported. Fixes stenciljs#6248
Adds tests covering all `overwriteExisting` modes on the `docs-readme` output target: - Always overwrite (`true`) - Overwrite if missing (`'if-missing'`) with and without a destination file - Never overwrite (`false`) - Default behaviour (`undefined`), which treats missing values as `false` Tests confirm that manual content is preserved when appropriate, new files are correctly generated when missing, and behaviour matches the original fix for stenciljs#5400. Also validates idempotent output across multiple overwriting scenarios. Related to the fix for stenciljs#6248.
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.
The
docs-readmeoutput target has long supported writing README files to custom locations using thedirproperty, helping teams structure their documentation workflows to suit project needs.As part of evolving those workflows, I've introduced the
overwriteExistingproperty to give developers precise control over how README files are handled. This addition supports common scenarios like always overwriting, only writing when files are missing, or preserving existing content:true),'if-missing'), orfalse).These options aim to better support workflows where documentation is closely tied to source code, while also offering flexibility for varied project structures.
What is the current behaviour?
By default, the docs-readme output target preserves any manually-entered content in destination README files, but it does not offer flexible controls for different overwrite behaviours. This made it difficult to manage workflows where documentation is expected to be tightly coupled with source code, while also needing different customisation strategies for various parts of a project.
Link to relevant issues/PRs: #5648 #6248
What is the new behaviour?
This PR introduces documentation for the new
overwriteExistingpropertyon the
docs-readmeoutput target.The documentation includes:
overwriteExistingconfiguration option.true,false, and'if-missing').stencil.config.tsfile.as the canonical source of truth for custom content.
Documentation
A documentation update has been made in stenciljs/site#1521.
Does this introduce a breaking change?
Testing
overwriteExistingproperty ondocs-readmeas described in bug: docs-readme output target no longer copies full content to dir path #6248.Other information
See #6248 for a detailed explanation of the use case this PR is covering.