bug: custom docs-readme directory

[oliveirarafa]

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.12.3

Current Behavior

When using docs-readme with the dir property in stencil.config.js, all my component readme.md files keep getting overwritten, including the text above the <!-- Auto Generated Below --> comment. According to this documentation https://stenciljs.com/docs/docs-readme#custom-markdown-content, I understand that text placed above the comment should be preserved.

   type: 'docs-readme',
   dir: "output"

I just noticed this as I'm creating this issue: If I have a readme.md with the <!-- Auto Generated Below --> comment and some text above it in the default output folder, this content above it is preserved.

Is this the intended feature? If so, I think it might just need a little tweak in the documentation.

Expected Behavior

Even when using the dir property to customize the output directory the content above <!-- Auto Generated Below --> should be preserved when generating another readme.md on build time.

System Info

System: node 20.11.0
    Platform: linux (5.15.133.1-microsoft-standard-WSL2)
   CPU Model: AMD Ryzen 7 5800H with Radeon Graphics (16 cpus)
    Compiler: /home/rafael/Projetos/stenciljs-custom-dir/node_modules/@stencil/core/compiler/stencil.js
       Build: 1708455660
     Stencil: 4.12.3 🐍
  TypeScript: 5.3.3
      Rollup: 2.56.3
      Parse5: 7.1.2
      jQuery: 4.0.0-pre
      Terser: 5.27.1

Steps to Reproduce

I created a repo to reproduce it. Just install the dependencies and run build.

https://github.com/oliveirarafa/stenciljs-custom-dir

• Without 'dir' (default output directory)

  Regenerating the readme.md keeps all the changes before the comment.

• With 'dir' (custom output directory)

  All the content before or after the comment is cleared.

  Note: just noticed that placing a readme.md in the default folder with the comment and a text before it makes this text persistent. In my opinion it makes more a little mor difficult to maintain because ir splits my docs in 2 but it works.

Code Reproduction URL

https://github.com/oliveirarafa/stenciljs-custom-dir

Additional Information

No response

[rwaskiewicz]

Thanks @oliveirarafa!

This does appear to be a bug in Stencil - when we look for a user's autogenerated content, we don't take the dir field into account. I'll get this labelled from someone to take a look. Thanks!

[alicewriteswrongs]

Hey @oliveirarafa, just had a chance to look into this and put together a change that I think should fix the issue.

If you want to give it a try I just published a dev build that you can install and try out:

npm install @stencil/core@4.15.0-dev.1712776573.8fd4e3

[oliveirarafa]

Hey @oliveirarafa, just had a chance to look into this and put together a change that I think should fix the issue.

If you want to give it a try I just published a dev build that you can install and try out:

npm install @stencil/core@4.15.0-dev.1712776573.8fd4e3

Thanks @alicewriteswrongs. I'll try it and let you know.

[christian-bromann]

@oliveirarafa the actual dev release version is 4.15.0-dev.1712776573.8fd4e34 so you can install it by running:

npm install @stencil/core@4.15.0-dev.1712776573.8fd4e34

[alicewriteswrongs]

oops I left off a 4! thanks for catching that @christian-bromann

[oliveirarafa]

@alicewriteswrongs @christian-bromann sorry for the delay, I couldn't test it earlier. I saw that the issue is closed but I tested it anyways and it worked. I was able to change the docs folder and the text before the comment is kept on further builds. Thank you!

[alicewriteswrongs]

Awesome, glad to hear it's working for you! The fix will be in the next release of Stencil :)