feat: support for YAML frontmatter (#71)

README.md

@@ -19,7 +19,9 @@ npm install -g @asyncapi/generator
 
 |Name|Description|Required|Default|Allowed values|Example|
 |---|---|---|---|---|---|
+|frontMatter|The name of a JSON or YAML formatted file containing values to provide the YAML frontmatter for static-site or documentation generators, just like [this](test/spec/ssg.yaml) one. The file may contain {{title}} and {{version}} tags. They are replaced with information for the AsyncAPI document that is under `info.title` and `info.version`. You can overwrite the version with `version` parameter. [Here](test/spec/slate.yaml) you can see an example that uses tags in frontmatter compatible with [slate](https://github.com/Slatedocs/Slate) |No|None|Any JSON or YAML formatted file|`slate.yaml`|
 |outFilename|The filename of the output file.|No|`asyncapi.md`|*Any* with `.md` extension|`index.md`|
+|toc|Include a Table-of-Contents in the output markdown.|No|`true`|`boolean`|`false`|
 |version|Override the version of your application provided under `info.version` location in the specification file.|No|Version is taken from the specification file.|Version is taken from the spec file. |`1.0.0`|
 
 
@@ -30,6 +32,8 @@ npm install -g @asyncapi/generator
 3. Generate output with watcher enabled by running the command `npm run dev`.
 4. Check generated markdown file located in `./test/output/asyncapi.md`.
 
+Parameters for the template are defined in `package.json`.
+
 ## Contributors ✨
 
 Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):

components/FrontMatter.js

@@ -0,0 +1,12 @@
+import { Text } from "@asyncapi/generator-react-sdk";
+
+import * as fs from "fs";
+import * as yaml from "yaml";
+
+export function FrontMatter({ asyncapi, params }) {
+  const frontMatter = yaml.parse(fs.readFileSync(params.frontMatter,'utf8'));
+  let frontMatterStr = yaml.stringify(frontMatter);
+  frontMatterStr = frontMatterStr.split('{{title}}').join(asyncapi.info().title());
+  frontMatterStr = frontMatterStr.split('{{version}}').join(params.version || asyncapi.info().version());
+  return <Text newLines={2}>{`---\n${frontMatterStr}---`}</Text>
+}

components/Message.js

@@ -1,7 +1,7 @@
 import { Text } from "@asyncapi/generator-react-sdk";
 import { generateExample, getHeadersExamples, getPayloadExamples } from "@asyncapi/generator-filters";
 
-import { Header, ListItem, CodeBlock } from "./common";
+import { Header, ListItem, CodeBlock, BlockQuote } from "./common";
 import { Schema } from "./Schema";
 
 export function Message({ message, title = 'Message' }) {
@@ -61,7 +61,7 @@ function Example({ type = 'headers', message }) {
     if (examples) {
       return (
         <>
-          <Header type={6}>Examples of headers</Header>
+          <BlockQuote>Examples of headers</BlockQuote>
           {examples.map(ex => (
             <Text newLines={2}>
               <CodeBlock language='json'>{JSON.stringify(ex, null, 2)}</CodeBlock>
@@ -73,7 +73,7 @@ function Example({ type = 'headers', message }) {
 
     return (
       <>
-        <Header type={6}>Examples of headers _(generated)_</Header>
+        <BlockQuote>Examples of headers _(generated)_</BlockQuote>
         <Text newLines={2}>
           <CodeBlock language='json'>{generateExample(message.headers().json())}</CodeBlock>
         </Text>
@@ -84,7 +84,7 @@ function Example({ type = 'headers', message }) {
     if (examples) {
       return (
         <>
-          <Header type={6}>Examples of payload</Header>
+          <BlockQuote>Examples of payload</BlockQuote>
           {examples.map(ex => (
             <Text newLines={2}>
               <CodeBlock language='json'>{JSON.stringify(ex, null, 2)}</CodeBlock>
@@ -96,11 +96,11 @@ function Example({ type = 'headers', message }) {
 
     return (
       <>
-        <Header type={6}>Examples of payload _(generated)_</Header>
+        <BlockQuote>Examples of payload _(generated)_</BlockQuote>
         <Text newLines={2}>
           <CodeBlock language='json'>{generateExample(message.payload().json())}</CodeBlock>
         </Text>
       </>
     );
   }
-}
+}

components/common.js

@@ -52,3 +52,8 @@ export function CodeBlock({ language = 'json', childrenContent = '' }) {
     </Text>
   );
 }
+
+export function BlockQuote({ childrenContent = "" }) {
+  return <Text newLines={2}>{`> ${childrenContent}`}</Text>
+}
+

package.json

@@ -31,7 +31,8 @@
   },
   "dependencies": {
     "@asyncapi/generator-filters": "^1.1.0",
-    "@asyncapi/generator-react-sdk": "^0.1.6"
+    "@asyncapi/generator-react-sdk": "^0.1.6",
+    "yaml": "^1.10.0"
   },
   "devDependencies": {
     "@semantic-release/commit-analyzer": "^8.0.1",
@@ -66,11 +67,20 @@
     "renderer": "react",
     "generator": ">=1.1.0 <2.0.0",
     "parameters": {
+      "frontMatter": {
+        "description": "The name of a JSON or YAML formatted file containing values to provide the YAML frontmatter for static-site or documentation generators. The file may contain {{title}} and {{version}} replaceable tags.",
+        "required": false
+      },
       "outFilename": {
         "description": "The name of the output markdown file",
         "default": "asyncapi.md",
         "required": false
       },
+      "toc": {
+        "description": "Include a Table-of-Contents in the output markdown.",
+        "default": "true",
+        "required": false
+      },
       "version": {
         "description": "Override the version of your application provided under `info.version` location in the specification file.",
         "required": false

template/asyncapi.js

@@ -4,12 +4,14 @@ import { Header, Link, ListItem } from "../components/common";
 import { Info, TermsOfService } from "../components/Info";
 import { Servers } from "../components/Servers";
 import { Channels } from "../components/Channels";
+import { FrontMatter } from "../components/FrontMatter";
 
 export default function({ asyncapi, params }) {
   return (
     <File name={params.outFilename || 'asyncapi.md'}>
+      {params.frontMatter && <FrontMatter asyncapi={asyncapi} params={params} />}
       <Info asyncapi={asyncapi} params={params} />
-      <TableOfContents asyncapi={asyncapi} />
+      {params.toc !== 'false' && <TableOfContents asyncapi={asyncapi} />}
       <TermsOfService asyncapi={asyncapi} />
       <Servers asyncapi={asyncapi} />
       <Channels asyncapi={asyncapi} />

test/spec/asyncapi.yml

@@ -96,7 +96,7 @@ channels:
         $ref: '#/components/messages/dimLight'
   some.channel:
     subscribe:
-      description: this doesn't show in markdown!
+      description: this description shows in markdown
       message:
         oneOf:
           - $ref: '#/components/messages/successMessage'

test/spec/slate.yaml

@@ -0,0 +1,11 @@
+---
+
+# example of a frontMatter file for the Slate documentation generator
+# see https://github.com/Slatedocs/Slate
+
+title: '{{title}} version {{version}}'
+language_tabs: [ { shell: "Shell" }, { javascript: "Node.js" } ]
+toc_footers: [ "Built with AsyncAPI/Generator" ]
+includes: []
+search: true
+code_clipboard: true

test/spec/ssg.yaml

@@ -0,0 +1,7 @@
+---
+
+# example of a frontMatter file for a static site generator
+
+title: AsyncAPI Documentation
+layout: asyncapi
+permalink: /asyncapi-docs