Add "title" option to add a global title at the beginning of the output file

README.md

@@ -54,6 +54,7 @@ Usage
 
 Options
   --ignore <globs csv>              - Glob patterns to exclude in 'dir'.
+  --title <title>                   - Adds title at the beginning of file.
   --toc                             - Adds table of the contents at the beginning of file.
   --decrease-title-levels           - Whether to decrease levels of all titles in markdown file to set them below file and directory title levels.
   --start-title-level-at <level no> - Level to start file and directory levels. Default: 1
@@ -247,6 +248,7 @@ Concat function options.
 - [joinString](#optional-joinstring)
 - [startTitleLevelAt](#optional-starttitlelevelat)
 - [titleKey](#optional-titlekey)
+- [title](#optional-title)
 - [toc](#optional-toc)
 - [tocLevel](#optional-toclevel)
 
@@ -322,6 +324,16 @@ Key name to get title in `FrontMatter` meta data in markdown headers.
 
 ---
 
+#### `Optional` title
+
+• **title**? : _undefined | string_
+
+_Defined in [index.ts:40](https://github.com/ozum/concat-md/blob/670ea75/src/index.ts#L39)_
+
+A global title to add at the beginning of the output.
+
+---
+
 #### `Optional` toc
 
 • **toc**? : _undefined | false | true_

src/bin/concat-md.ts

@@ -13,6 +13,7 @@ const lstat = fs.promises.lstat;
 interface Result extends meow.Result {
   flags: {
     ignore: string;
+    title: string;
     toc: boolean;
     tocLevel: string;
     decreaseTitleLevels: boolean;
@@ -29,6 +30,7 @@ interface Result extends meow.Result {
 /** @ignore */
 const FLAGS: meowOptions["flags"] = {
   ignore: { type: "string" },
+  title: { type: "string" },
   toc: { type: "boolean" },
   tocLevel: { type: "string" },
   decreaseTitleLevels: { type: "boolean" },
@@ -47,6 +49,7 @@ Usage
 
 Options
   --ignore <globs csv>              - Glob patterns to exclude in 'dir'.
+  --title <title>                   - Adds title at the beginning of file.
   --toc                             - Adds table of the contents at the beginning of file.
   --toc-level                       - Limit TOC entries to headings only up to the specified level. Default: 3
   --decrease-title-levels           - Whether to decrease levels of all titles in markdown file to set them below file and directory title levels.

src/index.ts

@@ -36,6 +36,10 @@ interface File {
  * Concat function options.
  */
 export interface ConcatOptions {
+  /**
+   * A global title to add at the beginning of the output.
+   */
+  title?: string;
   /**
    * Whether to add a table of contents.
    */
@@ -88,6 +92,7 @@ function arrify<T>(input: T | T[]): T[] {
 /**  @ignore */
 class MarkDownConcatenator {
   private dir: string;
+  private title?: string;
   private toc: boolean;
   private ignore: string | string[];
   private decreaseTitleLevels: boolean;
@@ -104,6 +109,7 @@ class MarkDownConcatenator {
   public constructor(
     dir: string,
     {
+      title,
       toc = false,
       tocLevel = 3,
       ignore = [],
@@ -116,6 +122,7 @@ class MarkDownConcatenator {
     }: ConcatOptions = {} as any
   ) {
     this.dir = dir;
+    this.title = title;
     this.toc = toc;
     this.tocLevel = tocLevel;
     this.ignore = ignore;
@@ -205,16 +212,23 @@ class MarkDownConcatenator {
     return title;
   }
 
-  private addToc(content: string): string {
+  private addGlobalTitleAndToc(content: string): string {
     if (!this.toc) {
+      if (this.title) {
+        return `# ${this.title}\n${content}`;
+      }
       return content;
     }
+
     const TOC_TAG = "<!-- START doctoc -->\n<!-- END doctoc -->";
     let result = content;
 
     if (!result.includes(TOC_TAG)) {
       result = `${TOC_TAG}\n\n${result}`;
     }
+    if (this.title) {
+      result = `# ${this.title}\n\n${result}`;
+    }
     const docTocResult = transform(result, "github.com", this.tocLevel, undefined, true);
     if (docTocResult.transformed) {
       result = docTocResult.data;
@@ -263,7 +277,7 @@ class MarkDownConcatenator {
     });
 
     const result = files.map(file => file.body).join(this.joinString);
-    return this.addToc(result);
+    return this.addGlobalTitleAndToc(result);
   }
 
   public async concat(): Promise<string> {

test/index.test.ts

@@ -63,6 +63,23 @@ describe("concat", () => {
     expect(result).toBe(expected);
   });
 
+  it("should add global title.", async () => {
+    const result = await concat(join(__dirname, "test-helper/main"), {
+      title: "Extra Title",
+    });
+    const expected = await getExpected("title.txt");
+    expect(result).toBe(expected);
+  });
+
+  it("should add global title and table of contents.", async () => {
+    const result = await concat(join(__dirname, "test-helper/main"), {
+      title: "Extra Title Before TOC",
+      toc: true,
+    });
+    const expected = await getExpected("title-and-toc.txt");
+    expect(result).toBe(expected);
+  });
+
   it("should convert links to titles from files", async () => {
     const result = await concat(join(__dirname, "test-helper/with-links"), { fileNameAsTitle: true, dirNameAsTitle: true });
     const expected = await getExpected("with-links-file-name-as-title.txt");

test/test-helper/expected/title-and-toc.txt

@@ -0,0 +1,32 @@
+# Extra Title Before TOC
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+
+
+- [Doc A](#doc-a)
+- [Doc B1](#doc-b1)
+- [Doc B2](#doc-b2)
+- [Doc BSub](#doc-bsub)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+
+<a name="dir-aamd"></a>
+
+# Doc A
+
+
+<a name="dir-bb1md"></a>
+
+# Doc B1
+
+
+<a name="dir-bb2md"></a>
+
+# Doc B2
+
+
+<a name="dir-bdir-b-subdir-b-sub-subb-submd"></a>
+
+# Doc BSub

test/test-helper/expected/title.txt

@@ -0,0 +1,20 @@
+# Extra Title
+
+<a name="dir-aamd"></a>
+
+# Doc A
+
+
+<a name="dir-bb1md"></a>
+
+# Doc B1
+
+
+<a name="dir-bb2md"></a>
+
+# Doc B2
+
+
+<a name="dir-bdir-b-subdir-b-sub-subb-submd"></a>
+
+# Doc BSub