graphql-markdown - npm Package Compare versions

Comparing version 7.1.0 to 7.2.0

package.json

 {
   "name": "graphql-markdown",
-  "version": "7.1.0",
+  "version": "7.2.0",
   "description": "Generate documentation for your GraphQL schema in Markdown",
@@ -5,0 +5,0 @@ "main": "src/index.js",

README.md

@@ -36,5 +36,11 @@ <div align="center">
 
-Installing the package adds a `graphql-markdown` script. Point it at a schema
-and the output will be written to stdout. You must install `graphql` alongside
-this package according to the
+Installing the package adds a `graphql-markdown` script via the standard package.json
+[`bin`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#bin) field – see
+npm’s [Executables](https://docs.npmjs.com/cli/v10/configuring-npm/folders#executables)
+documentation to learn where this will be on your system. For local installs,
+this is typically `node_modules/.bin`. When referencing the executable in
+your package.json’s `scripts`, you may simply call `graphql-markdown`.
+
+Point the `graphql-markdown` script at a schema and the output will be written
+to stdout. You must install `graphql` alongside this package according to the
 [compatible versions specified in `peerDependencies`](./package.json).
@@ -95,2 +101,6 @@
   --no-toc               Do not print table of contents
+  --toc-fields <list>    Expand the table of contents for the listed types
+                         (comma-separated) to link to fields within those types
+                         (e.g. --toc-fields "Query,Mutation,Subscription") or use
+                         the string "*" to link to fields for all types
   --prologue <string>    Include custom Markdown after the title
@@ -134,2 +144,5 @@ --epilogue <string>    Include custom Markdown after everything else
   is skipped.
+- **`tocFieldTypes`**: An array of type names whose table of contents entry will
+  be expanded to link to individual fields in a nested list. Include the special
+  name `*` in the array to match all types.
 - **`headingLevel`**: The initial level at which to render Markdown headings in
@@ -136,0 +149,0 @@ the output, defaults to 1. Use this if you are using `updateSchema` to embed

src/index.js

@@ -35,2 +35,6 @@ #!/usr/bin/env node
     --no-toc               Do not print table of contents
+    --toc-fields <list>    Expand the table of contents for the listed types
+                           (comma-separated) to link to fields within those types
+                           (e.g. --toc-fields "Query,Mutation,Subscription") or use
+                           the string "*" to link to fields for all types
     --prologue <string>    Include custom Markdown after the title
@@ -75,2 +79,5 @@ --epilogue <string>    Include custom Markdown after everything else
     }, {})
+    const tocFieldTypes = args['toc-fields']
+      ? args['toc-fields'].split(',')
+      : []
     const loadOptions = { headers }
@@ -85,2 +92,3 @@ loadSchemaJSON(schemaPath, loadOptions).then((schema) => {
         headingLevel: args['heading-level'],
+        tocFieldTypes,
       }
@@ -87,0 +95,0 @@ if (options.title === false) {

src/renderSchema.js

@@ -29,2 +29,3 @@ 'use strict'
   const getTypeURL = options.getTypeURL
+  const getFieldURL = options.getFieldURL
   const isInputObject = type.kind === 'INPUT_OBJECT'
@@ -55,9 +56,19 @@
   fields.forEach((field) => {
+    const url = getFieldURL(type, field)
+    const anchor = url && url.split('#')[1]
+    const fieldNameMarkup = anchor
+      ? `<strong id="${anchor}">${field.name}</strong>`
+      : `<strong>${field.name}</strong>`
     printer('<tr>')
     printer(
-      `<td colspan="2" valign="top"><strong>${field.name}</strong>${
+      `<td colspan="2" valign="top">${fieldNameMarkup}${
         field.isDeprecated ? ' ⚠️' : ''
       }</td>`
     )
-    printer(`<td valign="top">${renderType(field.type, { getTypeURL })}</td>`)
+    printer(
+      `<td valign="top">${renderType(field.type, {
+        getTypeURL,
+        getFieldURL,
+      })}</td>`
+    )
     if (field.description || field.isDeprecated) {
@@ -85,3 +96,8 @@ printer('<td>')
         printer(`<td colspan="2" align="right" valign="top">${arg.name}</td>`)
-        printer(`<td valign="top">${renderType(arg.type, { getTypeURL })}</td>`)
+        printer(
+          `<td valign="top">${renderType(arg.type, {
+            getTypeURL,
+            getFieldURL,
+          })}</td>`
+        )
         if (arg.description) {
@@ -112,2 +128,4 @@ printer('<td>')
   const unknownTypeURL = options.unknownTypeURL
+  const tocFieldTypes = options.tocFieldTypes || []
+  const tocFieldAllTypes = tocFieldTypes.includes('*')
 
@@ -122,2 +140,3 @@ if (schema.__schema) {
   }, {})
+
   const getTypeURL = (type) => {
@@ -134,2 +153,7 @@ const url = `#${type.name.toLowerCase()}`
 
+  const getFieldURL = (type, field) => {
+    const url = getTypeURL(type)
+    return url && `${url}.${field.name.toLowerCase()}`
+  }
+
   const queryType = schema.queryType
@@ -145,2 +169,3 @@ const query =
     types.find((type) => type.name === schema.subscriptionType.name)
+
   const objects = types.filter(
@@ -179,8 +204,23 @@ (type) =>
       printer('  * [Query](#query)')
+      if (tocFieldAllTypes || tocFieldTypes.includes(query.name)) {
+        query.fields.forEach((field) => {
+          printer(`    * [${field.name}](${getFieldURL(query, field)})`)
+        })
+      }
     }
     if (mutation) {
       printer('  * [Mutation](#mutation)')
+      if (tocFieldAllTypes || tocFieldTypes.includes(mutation.name)) {
+        mutation.fields.forEach((field) => {
+          printer(`    * [${field.name}](${getFieldURL(mutation, field)})`)
+        })
+      }
     }
     if (subscription) {
       printer('  * [Subscription](#subscription)')
+      if (tocFieldAllTypes || tocFieldTypes.includes(subscription.name)) {
+        subscription.fields.forEach((field) => {
+          printer(`    * [${field.name}](${getFieldURL(subscription, field)})`)
+        })
+      }
     }
@@ -191,2 +231,7 @@ if (objects.length) {
         printer(`    * [${type.name}](#${type.name.toLowerCase()})`)
+        if (tocFieldAllTypes || tocFieldTypes.includes(type.name)) {
+          type.fields.forEach((field) => {
+            printer(`      * [${field.name}](${getFieldURL(type, field)})`)
+          })
+        }
       })
@@ -198,2 +243,7 @@ }
         printer(`    * [${type.name}](#${type.name.toLowerCase()})`)
+        if (tocFieldAllTypes || tocFieldTypes.includes(type.name)) {
+          type.inputFields.forEach((field) => {
+            printer(`      * [${field.name}](${getFieldURL(type, field)})`)
+          })
+        }
       })
@@ -217,2 +267,7 @@ }
         printer(`    * [${type.name}](#${type.name.toLowerCase()})`)
+        if (tocFieldAllTypes || tocFieldTypes.includes(type.name)) {
+          type.fields.forEach((field) => {
+            printer(`      * [${field.name}](${getFieldURL(type, field)})`)
+          })
+        }
       })
@@ -235,3 +290,9 @@ }
     )
-    renderObject(query, { skipTitle: true, headingLevel, printer, getTypeURL })
+    renderObject(query, {
+      skipTitle: true,
+      headingLevel,
+      printer,
+      getTypeURL,
+      getFieldURL,
+    })
   }
@@ -250,2 +311,3 @@
       getTypeURL,
+      getFieldURL,
     })
@@ -267,2 +329,3 @@ }
       getTypeURL,
+      getFieldURL,
     })
@@ -274,3 +337,3 @@ }
     objects.forEach((type) =>
-      renderObject(type, { headingLevel, printer, getTypeURL })
+      renderObject(type, { headingLevel, printer, getTypeURL, getFieldURL })
     )
@@ -282,3 +345,3 @@ }
     inputs.forEach((type) =>
-      renderObject(type, { headingLevel, printer, getTypeURL })
+      renderObject(type, { headingLevel, printer, getTypeURL, getFieldURL })
     )
@@ -346,3 +409,3 @@ }
     interfaces.forEach((type) =>
-      renderObject(type, { headingLevel, printer, getTypeURL })
+      renderObject(type, { headingLevel, printer, getTypeURL, getFieldURL })
     )
@@ -373,2 +436,3 @@ }
             getTypeURL,
+            getFieldURL,
           })}</strong></td>`
@@ -375,0 +439,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

234680

increased by1.49%

Lines of code

793

increased by9.53%

Number of lines in readme file

186

increased by7.51%

No dependency changes