From 387c137f0bafa112bd322ef8be58819b0c945bda Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Fri, 26 Feb 2021 10:19:22 +0000 Subject: [PATCH] feat: support for YAML frontmatter (#71) --- README.md | 4 ++++ components/FrontMatter.js | 12 ++++++++++++ components/Message.js | 12 ++++++------ components/common.js | 5 +++++ package-lock.json | 3 +-- package.json | 12 +++++++++++- template/asyncapi.js | 4 +++- test/spec/asyncapi.yml | 2 +- test/spec/slate.yaml | 11 +++++++++++ test/spec/ssg.yaml | 7 +++++++ 10 files changed, 61 insertions(+), 11 deletions(-) create mode 100644 components/FrontMatter.js create mode 100644 test/spec/slate.yaml create mode 100644 test/spec/ssg.yaml diff --git a/README.md b/README.md index edd003f16..89e3c3ba1 100644 --- a/README.md +++ b/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)): diff --git a/components/FrontMatter.js b/components/FrontMatter.js new file mode 100644 index 000000000..2d1e8381d --- /dev/null +++ b/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 {`---\n${frontMatterStr}---`} +} diff --git a/components/Message.js b/components/Message.js index 4456b7e84..0c6fb2f86 100644 --- a/components/Message.js +++ b/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 ( <> -
Examples of headers
+
Examples of headers
{examples.map(ex => ( {JSON.stringify(ex, null, 2)} @@ -73,7 +73,7 @@ function Example({ type = 'headers', message }) { return ( <> -
Examples of headers _(generated)_
+
Examples of headers _(generated)_
{generateExample(message.headers().json())} @@ -84,7 +84,7 @@ function Example({ type = 'headers', message }) { if (examples) { return ( <> -
Examples of payload
+
Examples of payload
{examples.map(ex => ( {JSON.stringify(ex, null, 2)} @@ -96,11 +96,11 @@ function Example({ type = 'headers', message }) { return ( <> -
Examples of payload _(generated)_
+
Examples of payload _(generated)_
{generateExample(message.payload().json())} ); } -} \ No newline at end of file +} diff --git a/components/common.js b/components/common.js index faf262340..2d3509035 100644 --- a/components/common.js +++ b/components/common.js @@ -52,3 +52,8 @@ export function CodeBlock({ language = 'json', childrenContent = '' }) { ); } + +export function BlockQuote({ childrenContent = "" }) { + return {`> ${childrenContent}`} +} + diff --git a/package-lock.json b/package-lock.json index e7752aa28..0cf8aaf05 100644 --- a/package-lock.json +++ b/package-lock.json @@ -7689,8 +7689,7 @@ "yaml": { "version": "1.10.0", "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.0.tgz", - "integrity": "sha512-yr2icI4glYaNG+KWONODapy2/jDdMSDnrONSjblABjD9B4Z5LgiircSt8m8sRZFNi08kG9Sm0uSHtEmP3zaEGg==", - "dev": true + "integrity": "sha512-yr2icI4glYaNG+KWONODapy2/jDdMSDnrONSjblABjD9B4Z5LgiircSt8m8sRZFNi08kG9Sm0uSHtEmP3zaEGg==" }, "yaml-ast-parser": { "version": "0.0.43", diff --git a/package.json b/package.json index 7b52f3a6d..825e79691 100644 --- a/package.json +++ b/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 diff --git a/template/asyncapi.js b/template/asyncapi.js index 89801680b..8ec170874 100644 --- a/template/asyncapi.js +++ b/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 ( + {params.frontMatter && } - + {params.toc !== 'false' && } diff --git a/test/spec/asyncapi.yml b/test/spec/asyncapi.yml index 70b262710..d35f2c3ad 100644 --- a/test/spec/asyncapi.yml +++ b/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' diff --git a/test/spec/slate.yaml b/test/spec/slate.yaml new file mode 100644 index 000000000..6b1958908 --- /dev/null +++ b/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 diff --git a/test/spec/ssg.yaml b/test/spec/ssg.yaml new file mode 100644 index 000000000..f4c63409f --- /dev/null +++ b/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