graphql-markdown - npm Package Compare versions

Comparing version 3.1.0 to 3.2.0

package.json

 {
   "name": "graphql-markdown",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Generate documentation for your GraphQL schema in Markdown",
@@ -41,3 +41,3 @@ "main": "src/index.js",
   "devDependencies": {
-    "ava": "^0.22.0",
+    "ava": "^0.23.0",
     "coveralls": "^3.0.0",
@@ -44,0 +44,0 @@ "nyc": "^11.2.1",

README.md

@@ -45,2 +45,9 @@ [![npm version](https://img.shields.io/npm/v/graphql-markdown.svg)](https://www.npmjs.com/package/graphql-markdown)
 
+If `--update-file` is given, the generated Markdown will be output to the given
+file between the `<!-- START graphql-markdown -->` and `<!-- END graphql-markdown -->`
+comment markers instead of printed to STDOUT. If the file does not exist, it
+will be created (and will include the comment markers for future updates). Use
+this if you’d like to embed the rendered Markdown as just one part of a larger
+document (see also the `--heading-level` option).
+
 #### Options
@@ -50,2 +57,3 @@
 $ graphql-markdown --help
+
 Usage: graphql-markdown [options] <schema>
@@ -64,5 +72,10 @@
 
-  --title <string>       Change the document title (default: 'Schema Types')
-  --prologue <string>    Include custom Markdown at the beginning of the document
-  --epilogue <string>    Include custom Markdown at the end of the document
+  --title <string>       Change the top heading title (default: 'Schema Types')
+  --no-title             Do not print a default title
+  --prologue <string>    Include custom Markdown after the title
+  --epilogue <string>    Include custom Markdown after everything else
+  --heading-level <num>  Heading level to begin at, useful if you are embedding the
+                         output in a document with other sections (default: 1)
+  --update-file <file>   Markdown document to update (between comment markers) or
+                         create (if the file does not exist)
   --require <module>     If importing the schema from a module, require the specified
@@ -93,4 +106,7 @@ module first (useful for e.g. babel-register)
 * **`prologue`**: Markdown content to include after the title.
-* **`epilogue`**: Markdown content to include at the end of the document.
+* **`epilogue`**: Markdown content to include after everything else.
 * **`printer`**: A function to handle each line of output, defaults to `console.log`.
+* **`headingLevel`**: The initial level at which to render Markdown headings in
+  the output, defaults to 1. Use this if you are using `updateSchema` to embed
+  the output in a larger document with other sections.
 * **`unknownTypeURL`**: A string or function to determine the URL for linking to
@@ -102,2 +118,14 @@ types that aren’t found in the schema being rendered. This may be the case if
 
+#### updateSchema(path: string, schema: object, options: object)
+
+Given a path to a Markdown document, inject the output of `renderSchema` (with
+the given schema and options) into the document between the comment markers
+`<!-- START graphql-markdown -->` and `<!-- END graphql-markdown -->`. Returns a
+Promise.
+
+If the file does not exist, it will be created. If the document is empty, the
+necessary comment markers will automatically be inserted, but if there is
+existing content and no comment markers, the Promise will be rejected with an
+error.
+
 #### diffSchema(oldSchema: object, newSchema: object, options: object)
@@ -104,0 +132,0 @@

src/index.js

@@ -7,2 +7,3 @@ #!/usr/bin/env node
 const renderSchema = require('./renderSchema')
+const updateSchema = require('./updateSchema')
 const diffSchema = require('./diffSchema')
@@ -32,5 +33,10 @@
 
-    --title <string>       Change the document title (default: 'Schema Types')
-    --prologue <string>    Include custom Markdown at the beginning of the document
-    --epilogue <string>    Include custom Markdown at the end of the document
+    --title <string>       Change the top heading title (default: 'Schema Types')
+    --no-title             Do not print a default title
+    --prologue <string>    Include custom Markdown after the title
+    --epilogue <string>    Include custom Markdown after everything else
+    --heading-level <num>  Heading level to begin at, useful if you are embedding the
+                           output in a document with other sections (default: 1)
+    --update-file <file>   Markdown document to update (between comment markers) or
+                           create (if the file does not exist)
     --require <module>     If importing the schema from a module, require the specified
@@ -60,4 +66,35 @@ module first (useful for e.g. babel-register)
     loadSchemaJSON(schemaPath).then(schema => {
-      renderSchema(schema, args)
-      safeExit(0) // Prevents error when writing to a pipe.
+      const options = {
+        title: args.title,
+        skipTitle: false,
+        prologue: args.prologue,
+        epilogue: args.epilogue,
+        headingLevel: args['heading-level']
+      }
+      if (options.title === false) {
+        options.title = ''
+        options.skipTitle = true
+      } else if (Array.isArray(options.title)) {
+        options.title.forEach(value => {
+          if (typeof value === 'string') {
+            options.title = value
+          } else if (value === false) {
+            options.skipTitle = true
+          }
+        })
+      }
+      const updateFile = args['update-file']
+      if (updateFile) {
+        updateSchema(updateFile, schema, options)
+          .then(() => {
+            safeExit(0)
+          })
+          .catch(err => {
+            console.error(err)
+            safeExit(1)
+          })
+      } else {
+        renderSchema(schema, options)
+        safeExit(0)
+      }
     })
@@ -73,3 +110,4 @@ } else {
   renderSchema,
+  updateSchema,
   diffSchema
 }

src/renderSchema.js

 'use strict'
-
 function sortBy (arr, property) {
@@ -28,6 +27,7 @@ arr.sort((a, b) => {
   const printer = options.printer || console.log
+  const headingLevel = options.headingLevel || 1
   const getTypeURL = options.getTypeURL
 
   if (!skipTitle) {
-    printer(`\n### ${type.name}\n`)
+    printer(`\n${'#'.repeat(headingLevel + 2)} ${type.name}\n`)
   }
@@ -96,5 +96,7 @@ if (type.description) {
   const title = options.title || 'Schema Types'
+  const skipTitle = options.skipTitle || false
   const prologue = options.prologue || ''
   const epilogue = options.epilogue || ''
   const printer = options.printer || console.log
+  const headingLevel = options.headingLevel || 1
   const unknownTypeURL = options.unknownTypeURL
@@ -134,3 +136,5 @@
 
-  printer(`# ${title}\n`)
+  if (!skipTitle) {
+    printer(`${'#'.repeat(headingLevel)} ${title}\n`)
+  }
 
@@ -174,16 +178,20 @@ if (prologue) {
     printer(
-      `\n## Query ${query.name === 'Query' ? '' : '(' + query.name + ')'}`
+      `\n${'#'.repeat(headingLevel + 1)} Query ${query.name === 'Query'
+        ? ''
+        : '(' + query.name + ')'}`
     )
-    renderObject(query, { skipTitle: true, printer, getTypeURL })
+    renderObject(query, { skipTitle: true, headingLevel, printer, getTypeURL })
   }
 
   if (objects.length) {
-    printer('\n## Objects')
-    objects.forEach(type => renderObject(type, { printer, getTypeURL }))
+    printer(`\n${'#'.repeat(headingLevel + 1)} Objects`)
+    objects.forEach(type =>
+      renderObject(type, { headingLevel, printer, getTypeURL })
+    )
   }
 
   if (enums.length) {
-    printer('\n## Enums')
+    printer(`\n${'#'.repeat(headingLevel + 1)} Enums`)
     enums.forEach(type => {
-      printer(`\n### ${type.name}\n`)
+      printer(`\n${'#'.repeat(headingLevel + 2)} ${type.name}\n`)
       if (type.description) {
@@ -230,5 +238,5 @@ printer(`${type.description}\n`)
   if (scalars.length) {
-    printer('\n## Scalars\n')
+    printer(`\n${'#'.repeat(headingLevel + 1)} Scalars\n`)
     scalars.forEach(type => {
-      printer(`### ${type.name}\n`)
+      printer(`${'#'.repeat(headingLevel + 2)} ${type.name}\n`)
       if (type.description) {
@@ -241,4 +249,6 @@ printer(`${type.description}\n`)
   if (interfaces.length) {
-    printer('\n## Interfaces\n')
-    interfaces.forEach(type => renderObject(type, { printer, getTypeURL }))
+    printer(`\n${'#'.repeat(headingLevel + 1)} Interfaces\n`)
+    interfaces.forEach(type =>
+      renderObject(type, { headingLevel, printer, getTypeURL })
+    )
   }
@@ -245,0 +255,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

169834

increased by3.44%

Number of package files

9

increased by12.5%

Lines of code

574

increased by22.65%

Number of lines in readme file

147

increased by23.53%

Worsened metrics

Number of low supply chain risk alerts

6

increased by20%

No dependency changes