npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

graphql-storm-markdown

v1.0.1

Published

Generate documentation for your GraphQL schema in Markdown

Downloads

6

Readme

graphql-storm-markdown

The easiest way to document your GraphQL schema.

npm version

Note: this is a clone of graphql-markdown but adapted due to changes needed in the output template.


This package will generate Markdown that beautifully renders your GraphQL schema in an easily explorable document.

$ yarn add graphql-storm-markdown --dev
$ npm install graphql-storm-markdown --save-dev

[See an example][example] generated from the [GraphBrainz][] schema.

Usage

Command Line API

Installing the package adds a graphql-storm-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 compatible versions specified in peerDependencies.

The schema may be retrieved from a GraphQL endpoint:

$ graphql-storm-markdown http://your-server.com/graphql > schema.md

…or a module exporting an instance of GraphQLSchema:

$ graphql-storm-markdown ./path/to/schema.js > schema.md

…or a file containing GraphQL syntax:

$ graphql-storm-markdown ./path/to/schema.graphql > schema.md

…or a file containing the JSON output of an introspection query:

$ graphql-storm-markdown ./path/to/schema.json > schema.md

If --update-file is given, the generated Markdown will be output to the given file between the <!-- START graphql-storm-markdown --> and <!-- END graphql-storm-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

$ graphql-storm-markdown --help

Usage: graphql-storm-markdown [options] <schema>

Output a Markdown document with rendered descriptions and links between types.
The schema may be specified as:

  - a URL to the GraphQL endpoint (the introspection query will be run)
  - a GraphQL document containing the schema (.graphql or .gql)
  - a JSON document containing the schema (as returned by the introspection query)
  - an importable module with the schema as its default export (either an instance
    of GraphQLSchema or a JSON object)

Options:

  --title <string>       Change the top heading title (default: 'Schema Types')
  --no-title             Do not print a default title
  --no-toc               Do not print table of contents
  --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
                         module first (useful for e.g. babel-register)
  --header <name=value>  Additional header(s) to use in GraphQL request
                         e.g. --header "Authorization=Bearer ey..."
  --version              Print version and exit

Node API

The following functions are exported from the graphql-storm-markdown module for programmatic use.

loadSchemaJSON(schemaPath: string, options: object)

Given a string pointing to a GraphQL schema (URL, module, or file path), get the result of the introspection query, suitable for use as input to renderSchema.

renderSchema(schema: object, options: object)

Given a schema JSON object (the output of the introspection query, an object with a __schema property), render the schema to the console or the provided printer function.

Options
  • title: The title of the document, defaults to “Schema Types”.
  • prologue: Markdown content to include after the title.
  • epilogue: Markdown content to include after everything else.
  • printer: A function to handle each line of output, defaults to console.log.
  • skipTableOfContents: When set, rendering of "Table of contents" section is skipped.
  • 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 types that aren’t found in the schema being rendered. This may be the case if you’re rendering the result of diffSchema(), for example. String values will have #${type.name.toLowerCase()} appended, and function values will be called with the type object for full control.

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-storm-markdown --> and <!-- END graphql-storm-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)

Given two schema JSON objects (the results of the introspection query on two schemas), return a new schema JSON object containing only the added or updated types and fields. You can use this to document a schema update, or to document the effects of a schema extension (e.g. extend type definitions).

Options
  • processTypeDiff: A function to add or modify fields on each type that will be output.

Output

Output is optimized for display on GitHub, using GitHub Flavored Markdown. Due to the complexity of the tables in the generated document, much of the table output is raw HTML (as allowed by Markdown).