docs-readme + dir

[oliveirarafa]

Anyone knows why using

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

on stencil.config.js keeps clearing my readme.md every build?

Even the text above gets cleared.

[christian-bromann]

Hey @oliveirarafa 👋

The docs-readme output target auto generates component docs for your Stencil project. It is not recommend to make manual edits to the markdown itself as they get overwritten. Instead add the docs to the component.

Even the text above gets cleared.

What "text above" are you referring to?

[oliveirarafa]

Hi @christian-bromann. Thank you for helping me.

The text above that I mentioned refers to placing some text above the <!-- Auto Generated Below --> comment. After reading the documentation on https://stenciljs.com/docs/docs-readme#custom-markdown-content, I understood that placing some intended text above this comment would make it 'permanent' between builds. It does appear to work as expected, but when I change the default folders, this behavior disappears.

[oliveirarafa]

Just another note, what I'm trying to do is create a Docusaurus static site that pulls some of the documentation from this file. This would assist me and my teams in always keeping the props, events, and slots up to date.

[christian-bromann]

This sounds like a great idea. Can you elaborate on the part on changing the default folder? Why is that needed for you?

[oliveirarafa]

Yeah, no problem.

We are in the process of rewriting our web components library using StencilJS. Alongside this, I'm exploring new ways to make it easier to create, test, and document our components. I've noticed that many libraries, including Ionic, use Docusaurus. Therefore, I'm trying to improve its integration with the autogenerated StencilJS docs.

The need to change the default directory arises because Docusaurus is 'another app' within my monorepo. I'm unsure how I would display the autogenerated docs if they were in different projects.

Also, someone on discord asked if I could create an issue about this, so I created this issue: #5400

[christian-bromann]

Cool, let's continue convo there.