fix(docs): respect custom README content when writing to a custom path

src/compiler/docs/generate-doc-data.ts

@@ -377,7 +377,10 @@ export const getNameText = (name: string, tags: d.JsonDocsTag[]) => {
  * @returns the user generated content that occurs before {@link AUTO_GENERATE_COMMENT}. If no user generated content
  * exists, or if there was an issue reading the file, return `undefined`
  */
-const getUserReadmeContent = async (compilerCtx: d.CompilerCtx, readmePath: string): Promise<string | undefined> => {
+export const getUserReadmeContent = async (
+  compilerCtx: d.CompilerCtx,
+  readmePath: string,
+): Promise<string | undefined> => {
   try {
     const existingContent = await compilerCtx.fs.readFile(readmePath);
     // subtract one to get everything up to, but not including the auto generated comment

src/compiler/docs/readme/output-docs.ts

@@ -1,7 +1,8 @@
-import { join, relative } from '@utils';
+import { join, normalizePath, relative } from '@utils';
 
 import type * as d from '../../../declarations';
 import { AUTO_GENERATE_COMMENT } from '../constants';
+import { getUserReadmeContent } from '../generate-doc-data';
 import { stylesToMarkdown } from './markdown-css-props';
 import { depsToMarkdown } from './markdown-dependencies';
 import { eventsToMarkdown } from './markdown-events';
@@ -12,6 +13,23 @@ import { propsToMarkdown } from './markdown-props';
 import { slotsToMarkdown } from './markdown-slots';
 import { usageToMarkdown } from './markdown-usage';
 
+/**
+ * Generate a README for a given component and write it to disk.
+ *
+ * Typically the README is going to be a 'sibling' to the component's source
+ * code (i.e. written to the same directory) but the user may also configure a
+ * custom output directory by setting {@link d.OutputTargetDocsReadme.dir}.
+ *
+ * Output readme files also include {@link AUTO_GENERATE_COMMENT}, and any
+ * text located _above_ that comment is preserved when the new readme is written
+ * to disk.
+ *
+ * @param config a validated Stencil config
+ * @param compilerCtx the current compiler context
+ * @param readmeOutputs docs-readme output targets
+ * @param docsData documentation data for the component of interest
+ * @param cmps metadata for all the components in the project
+ */
 export const generateReadme = async (
   config: d.ValidatedConfig,
   compilerCtx: d.CompilerCtx,
@@ -25,10 +43,20 @@ export const generateReadme = async (
   await Promise.all(
     readmeOutputs.map(async (readmeOutput) => {
       if (readmeOutput.dir) {
-        const readmeContent = generateMarkdown(userContent, docsData, cmps, readmeOutput);
-        const relPath = relative(config.srcDir, docsData.readmePath);
-        const absPath = join(readmeOutput.dir, relPath);
-        const results = await compilerCtx.fs.writeFile(absPath, readmeContent);
+        const relativeReadmePath = relative(config.srcDir, docsData.readmePath);
+        const readmeOutputPath = join(readmeOutput.dir, relativeReadmePath);
+
+        const currentReadmeContent =
+          normalizePath(readmeOutput.dir) !== normalizePath(config.srcDir)
+            ? // The user set a custom `.dir` property, which is where we're going
+              // to write the updated README. We need to read the non-automatically
+              // generated content from that file and preserve that.
+              await getUserReadmeContent(compilerCtx, readmeOutputPath)
+            : userContent;
+
+        const readmeContent = generateMarkdown(currentReadmeContent, docsData, cmps, readmeOutput);
+
+        const results = await compilerCtx.fs.writeFile(readmeOutputPath, readmeContent);
         if (results.changedContent) {
           if (isUpdate) {
             config.logger.info(`updated readme docs: ${docsData.tag}`);
@@ -42,15 +70,15 @@ export const generateReadme = async (
 };
 
 export const generateMarkdown = (
-  userContent: string,
+  userContent: string | undefined,
   cmp: d.JsonDocsComponent,
   cmps: d.JsonDocsComponent[],
   readmeOutput: d.OutputTargetDocsReadme,
 ) => {
   //If the readmeOutput.dependencies is true or undefined the dependencies will be generated.
   const dependencies = readmeOutput.dependencies !== false ? depsToMarkdown(cmp, cmps) : [];
   return [
-    userContent,
+    userContent || '',
     AUTO_GENERATE_COMMENT,
     '',
     '',
@@ -78,6 +106,12 @@ const getDocsDeprecation = (cmp: d.JsonDocsComponent) => {
   return [];
 };
 
+/**
+ * Get a minimal default README for a Stencil component
+ *
+ * @param docsData documentation data for the component of interest
+ * @returns a minimal README template for that component
+ */
 const getDefaultReadme = (docsData: d.JsonDocsComponent) => {
   return [`# ${docsData.tag}`, '', '', ''].join('\n');
 };

src/declarations/stencil-public-compiler.ts

@@ -2266,6 +2266,11 @@ export interface OutputTargetDocsVscode extends OutputTargetBase {
 
 export interface OutputTargetDocsReadme extends OutputTargetBase {
   type: 'docs-readme';
+  /**
+   * The root directory where README files should be written
+   *
+   * defaults to {@link Config.srcDir}
+   */
   dir?: string;
   dependencies?: boolean;
   footer?: string;

test/docs-readme/custom-readme-output/components/styleurls-component/readme.md

@@ -0,0 +1,22 @@
+# styleurls-component
+
+This file is in a custom location, set with `.dir` on the `docs-readme` OT.
+
+The content here above the 'auto-generation' comment shouldn't be overwritten.
+
+This is a regression test for the issue reported in ionic-team/stencil#5400.
+
+<!-- Auto Generated Below -->
+
+
+## CSS Custom Properties
+
+| Name    | Description  |
+| ------- | ------------ |
+| `--one` | Property One |
+| `--two` | Property Two |
+
+
+----------------------------------------------
+
+*Built with [StencilJS](https://stenciljs.com/)*

test/docs-readme/stencil.config.ts

@@ -9,5 +9,9 @@ export const config: Config = {
     {
       type: 'dist',
     },
+    {
+      type: 'docs-readme',
+      dir: 'custom-readme-output',
+    },
   ],
 };