Prerequisites

• I have read the Contributing Guidelines.
• I agree to follow the Code of Conduct.
• I have searched for existing issues that already report this problem, without success.

Stencil Version

4.30.0 🌺

Current Behavior

When using the docs-readme output target in Stencil with the dir property set to copy generated component README files into another directory (in this case, our Docusaurus documentation folder), custom content in the destination readmes is being erased during build. Previously, Stencil would copy the full content of the component README into the dir path, allowing us to use our component readmes as the source of truth for documentation across platforms.

After upgrading to a version that includes PR #5648, we’ve observed that:

• If the destination readme does not already exist, the copied file only includes the autogenerated content (starting from <!-- Auto Generated Below -->) and lacks any content above it.
• If the file does exist and contains custom content, that content is preserved.
• There is no option to force an overwrite or fallback to full copy behaviour when the file is missing.

This breaks our workflow, which relies on Stencil outputting the entire component README into the documentation platform directory. Previously, this approach allowed us to centralize our documentation within the component readmes –making them consistently visible across GitHub, GitLab, and our Docusaurus site without maintaining duplicate copies.

As mentioned in alicewriteswrongs' comment:

the way this is built we just don't have a 'canonical' README location or a way to specify that at present

This limitation is at the heart of the issue we've run into. We were treating the component readmes as the central documentation authority, and the current behaviour prevents us from continuing to do so without adding custom build steps or manual interventions.

Expected Behavior

When using the docs-readme output target with a specified dir, Stencil should:

• Copy the entire content of the component README to the target directory on first build, if the destination file does not exist.
• Retain any existing custom content in the destination file, and update only the autogenerated section during subsequent builds.
• Provide an option to opt into this behaviour, or alternatively, offer a setting that allows for full-file overwrite or selective merging.

This would allow developers to maintain a single README per component as the definitive documentation source, while still benefiting from Stencil’s auto-generated metadata updates. Ideally, the behaviour would match the pre-#5648 implementation, or give users a clear mechanism to restore that functionality.

System Info

System: node 20.18.1
    Platform: linux (5.15.167.4-microsoft-standard-WSL2)
   CPU Model: 12th Gen Intel(R) Core(TM) i7-12700H (20 cpus)
    Compiler: /home/scott/source/sample-stenciljs-with-docs/node_modules/@stencil/core/compiler/stencil.js
       Build: 1745512551
     Stencil: 4.30.0 🌺
  TypeScript: 5.5.4
      Rollup: 4.34.9
      Parse5: 7.2.1
      jQuery: 4.0.0-pre
      Terser: 5.37.0

Steps to Reproduce

1. Clone the reproduction repo: smorrisods/sample-stenciljs-with-docs
2. Navigate to the root and install dependencies:

   npm install

3. Run the build and start scripts:

   npm run start

4. Observe the output in packages/library-docs/docs/components/my-component/README.md
   • If the file does not already exist, it is created with only autogenerated content (i.e., from <!-- Auto Generated Below --> downward), and any intended manual content above that line is missing.
5. Manually add custom content above the autogenerated block in the destination readme.
6. Re-run the build process.
   • Note that the custom content is now retained.

This demonstrates that the docs-readme output behaviour depends on the file's pre-existence and does not allow for full content generation when the destination file is absent.

Code Reproduction URL

https://github.com/smorrisods/sample-stenciljs-with-docs

Additional Information

I really like the new functionality introduced by the updated docs-readme behaviour as it gives users more control over autogenerated documentation content. However, I also found the old behaviour useful for workflows where documentation is tightly coupled with source code. Ideally, it would be possible to configure this on a per-output-target basis, enabling both styles to coexist within a single project.

Such flexibility would make it easier to support use cases where a project might want different versions or formats of documentation in different locations; some fully autogenerated, others custom-augmented.