Merge branch 'feature/custom-readme' into develop

Author: GerkinDev

packages/plugin-monorepo-readmes/src/find-readme-file.spec.ts

@@ -30,12 +30,17 @@ describe( 'Readme file location', () => {
 				},
 				'package.json': '',
 				'README.md': 'hello',
+				'OTHER.md': 'yellow',
 			},
 		} );
-		expect( findReadmeFile( [ 'package.json' ], buildMapping( 'foo/src/index.ts' ) ) ).toEqual( {
+		expect( findReadmeFile( [ 'package.json' ], buildMapping( 'foo/src/index.ts' ), [] ) ).toEqual( {
 			relative: 'README.md',
 			absolute: resolve( rootDir, 'foo/README.md' ),
 		} );
+		expect( findReadmeFile( [ 'package.json' ], buildMapping( 'foo/src/index.ts' ), [ 'OTHER.md' ] ) ).toEqual( {
+			relative: 'OTHER.md',
+			absolute: resolve( rootDir, 'foo/OTHER.md' ),
+		} );
 	} );
 	it( 'should return "undefined" if no readme is found along with the "package.json" file', () => {
 		setVirtualFs( {
@@ -47,7 +52,8 @@ describe( 'Readme file location', () => {
 				'package.json': '',
 			},
 		} );
-		expect( findReadmeFile( [ 'package.json' ], buildMapping( 'foo/src/index.ts' ) ) ).toEqual( undefined );
+		expect( findReadmeFile( [ 'package.json' ], buildMapping( 'foo/src/index.ts' ), [] ) ).toEqual( undefined );
+		expect( findReadmeFile( [ 'package.json' ], buildMapping( 'foo/src/index.ts' ), [ 'OTHER.md' ] ) ).toEqual( undefined );
 	} );
 	it( 'should fallback on each readme targets', () => {
 		setVirtualFs( {
@@ -61,11 +67,16 @@ describe( 'Readme file location', () => {
 				},
 				'project.json': '',
 				'readme.md': '',
+				'other.md': '',
 			},
 		} );
-		expect( findReadmeFile( [ 'package.json', 'project.json' ], buildMapping( 'foo/bar/src/index.ts' ) ) ).toEqual( {
+		expect( findReadmeFile( [ 'package.json', 'project.json' ], buildMapping( 'foo/bar/src/index.ts' ), [] ) ).toEqual( {
 			relative: 'readme.md',
 			absolute: resolve( rootDir, 'foo/readme.md' ),
 		} );
+		expect( findReadmeFile( [ 'package.json', 'project.json' ], buildMapping( 'foo/bar/src/index.ts' ), [ 'other.md' ] ) ).toEqual( {
+			relative: 'other.md',
+			absolute: resolve( rootDir, 'foo/other.md' ),
+		} );
 	} );
 } );

packages/plugin-monorepo-readmes/src/find-readme-file.ts

@@ -13,14 +13,24 @@ const getModuleReflectionSource = ( reflection: DeclarationReflection ) => {
 	return undefined;
 };
 
+const findReadmeInDir = ( dir: string, readmeFile: string[] ) => readdirSync( dir ).find( f => readmeFile.includes( f.toLowerCase() ) );
+
 /**
  * Try to resoluve the README file in the directory of the module's `package.json`.
  *
  * @param readmeTargets - A list of file names to look up to locate packages root.
  * @param moduleMapping - The module URL mapping.
+ * @param readmeCandidates - A list of files to use as readme. The first found is used. File names are NOT case sensitive. Example: `["readme-typedoc.md", "readme.md"]`. Defaults to `["readme.md"]`.
  * @returns the relative & absolute path of the readme.
  */
-export const findReadmeFile = ( readmeTargets: string[], moduleMapping: UrlMapping<DeclarationReflection> ) => {
+export const findReadmeFile = ( readmeTargets: string[], moduleMapping: UrlMapping<DeclarationReflection>, readmeCandidates?: string[] ) => {
+	if( !readmeCandidates ){
+		readmeCandidates = [];
+	}
+	if( readmeCandidates.length === 0 ) {
+		readmeCandidates.push( 'readme.md' );
+	}
+	readmeCandidates = readmeCandidates.map( r => r.toLowerCase() );
 	const src = getModuleReflectionSource( moduleMapping.model );
 	if( !src ){
 		return;
@@ -32,7 +42,8 @@ export const findReadmeFile = ( readmeTargets: string[], moduleMapping: UrlMappi
 			continue;
 		}
 		const pkgDir = dirname( targetFile );
-		const readmeFile = readdirSync( pkgDir ).find( f => f.toLowerCase() === 'readme.md' );
+		const readmeFile = findReadmeInDir( pkgDir, readmeCandidates );
+
 		if( readmeFile ){
 			const absReadmeFile = resolve( pkgDir, readmeFile );
 			return {

packages/plugin-monorepo-readmes/src/options/build.ts

@@ -17,4 +17,9 @@ export const buildOptions = ( plugin: MonorepoReadmePlugin ) => OptionGroup.fact
 		map: LogLevel,
 		defaultValue: plugin.application.logger.level,
 	} )
+	.add( 'readme', {
+		help: 'Specify name of readme files',
+		type: ParameterType.Array,
+		defaultValue: [],
+	} )
 	.build();

packages/plugin-monorepo-readmes/src/options/types.ts

@@ -17,5 +17,12 @@ export interface IPluginOptions {
 	 * @default application.logger.level
 	 */
 	logLevel: LogLevel;
+
+	/**
+	 * The name of the readme files
+	 *
+	 * @default `[]`
+	 */
+	readme: string[];
 }
 

packages/plugin-monorepo-readmes/src/plugin.ts

@@ -41,7 +41,7 @@ export class MonorepoReadmePlugin extends ABasePlugin {
 	 * @param moduleMapping - The module URL mapping to modify
 	 */
 	private _modifyModuleIndexPage( theme: DefaultTheme, moduleMapping: UrlMapping<DeclarationReflection> ){
-		const readme = findReadmeFile( this.pluginOptions.getValue().rootFiles, moduleMapping );
+		const readme = findReadmeFile( this.pluginOptions.getValue().rootFiles, moduleMapping, this.pluginOptions.getValue().readme );
 		if( !readme ){
 			return;
 		}