Proposal: Include README as component documentation upon packaging

Describe the problem

At work we have a component library based on Bootstrap. We have created the components in their own folder so each folder may have a README. This helps co-workers understand each component in more detail when visiting the GitHub repository and navigating to the component's folder.

Well, we decided it would be nice if the README were included as component documentation at the end of the component's source:

<!--
@component

README CONTENTS HERE
-->

Yes, we can handle this in CI/CD, no problem. It would be nice, though, if Svelte did it for us upon packaging. It would also help people that maintain project libraries for free that have no resources for CI/CD or automation, or simply don't know about this, and users of the component can benefit by acquiring more information through Intellisense.

Describe the proposed solution

Basically, npm run package would, by default, include the contents of the README file in the component as described above if:

• The component resides in its own folder under /src/lib.
• The README's first line is, exactly # <Component>, where <Component> is the component's name.
• No explicit switch or flag has been set to turn this feature off.

It would be a feature on by default to automatically rip the benefits on libraries.

A catch:

If a folder contains more than one component, maybe the README is divided, so the contents of README need to be distributed among all components. We at work, are using this convention:

# <Component name, equals to the component's file name>

...

---

# <Another component>

...

We are keeping closely related or dependant components in the same folder, and because GitHub only shows one README, we have been reluctant to create one README per component because then GitHub visitors won't see the information of all components.

Importance

nice to have

Start with the npm run package entry point and inspect how components under /src/lib are packaged. Compare the proposal's README conventions, including folders with multiple components, and determine how opt-out behavior should work. Done means packaged components include the specified README documentation without breaking existing packaging.