{"id":13553530,"url":"https://github.com/exogen/graphql-markdown","last_synced_at":"2025-05-15T10:03:11.520Z","repository":{"id":18849250,"uuid":"75462377","full_name":"exogen/graphql-markdown","owner":"exogen","description":"The easiest way to document your GraphQL schema.","archived":false,"fork":false,"pushed_at":"2024-11-21T19:06:32.000Z","size":501,"stargazers_count":185,"open_issues_count":4,"forks_count":55,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-05-08T18:47:54.458Z","etag":null,"topics":["docgen","docs","documentation-generator","github","graphql","markdown"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/exogen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"exogen","buy_me_a_coffee":"mosswood"}},"created_at":"2016-12-03T08:39:08.000Z","updated_at":"2025-04-30T02:07:39.000Z","dependencies_parsed_at":"2024-06-18T14:01:42.323Z","dependency_job_id":"7587fd91-354b-4cf8-b51c-393c1dc95363","html_url":"https://github.com/exogen/graphql-markdown","commit_stats":{"total_commits":103,"total_committers":11,"mean_commits":9.363636363636363,"dds":0.4077669902912622,"last_synced_commit":"cc93fd1ddbbeae2d4f725810ef545359f16ada52"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exogen%2Fgraphql-markdown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exogen%2Fgraphql-markdown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exogen%2Fgraphql-markdown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/exogen%2Fgraphql-markdown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/exogen","download_url":"https://codeload.github.com/exogen/graphql-markdown/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254319716,"owners_count":22051072,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docgen","docs","documentation-generator","github","graphql","markdown"],"created_at":"2024-08-01T12:02:27.349Z","updated_at":"2025-05-15T10:03:04.409Z","avatar_url":"https://github.com/exogen.png","language":"JavaScript","readme":"\u003cdiv align=\"center\"\u003e\n\n# graphql-markdown\n\n**The easiest way to document your GraphQL schema.**\n\n[![npm version](https://img.shields.io/npm/v/graphql-markdown.svg)](https://www.npmjs.com/package/graphql-markdown)\n\n\u003c/div\u003e\n\n---\n\nThis package will generate Markdown that beautifully renders your GraphQL schema\nin an easily explorable document.\n\n```console\n$ yarn add graphql-markdown --dev\n$ npm install graphql-markdown --save-dev\n```\n\n**[See an example][example]** generated from the [GraphBrainz][] schema.\n\n## Support\n\nDid this project bring you joy? Want to support updates? Check out\n[my GitHub Sponsors page](https://github.com/sponsors/exogen).\n\nAlternatively…\n\n\u003ca href=\"https://www.buymeacoffee.com/mosswood\" target=\"_blank\"\u003e\u003cimg src=\"https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png\" alt=\"Buy Me A Coffee\" style=\"height: 60px !important;width: 217px !important;\"\u003e\u003c/a\u003e\n\n## Usage\n\n### Command Line API\n\nInstalling the package adds a `graphql-markdown` script via the standard package.json\n[`bin`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#bin) field – see\nnpm’s [Executables](https://docs.npmjs.com/cli/v10/configuring-npm/folders#executables)\ndocumentation to learn where this will be on your system. For local installs,\nthis is typically `node_modules/.bin`. When referencing the executable in\nyour package.json’s `scripts`, you may simply call `graphql-markdown`.\n\nPoint the `graphql-markdown` script at a schema and the output will be written\nto stdout. You must install `graphql` alongside this package according to the\n[compatible versions specified in `peerDependencies`](./package.json).\n\nThe schema may be retrieved from a GraphQL endpoint:\n\n```console\n$ graphql-markdown http://your-server.com/graphql \u003e schema.md\n```\n\n…or a module exporting an instance of `GraphQLSchema`:\n\n```console\n$ graphql-markdown ./path/to/schema.js \u003e schema.md\n```\n\n…or a file containing GraphQL syntax:\n\n```console\n$ graphql-markdown ./path/to/schema.graphql \u003e schema.md\n```\n\n…or a file containing the JSON output of an introspection query:\n\n```console\n$ graphql-markdown ./path/to/schema.json \u003e schema.md\n```\n\nIf `--update-file` is given, the generated Markdown will be output to the given\nfile between the `\u003c!-- START graphql-markdown --\u003e` and\n`\u003c!-- END graphql-markdown --\u003e` comment markers instead of printed to STDOUT. If\nthe file does not exist, it will be created (and will include the comment\nmarkers for future updates). Use this if you’d like to embed the rendered\nMarkdown as just one part of a larger document (see also the `--heading-level`\noption).\n\n#### Options\n\n```console\n$ graphql-markdown --help\n\nUsage: graphql-markdown [options] \u003cschema\u003e\n\nOutput a Markdown document with rendered descriptions and links between types.\nThe schema may be specified as:\n\n  - a URL to the GraphQL endpoint (the introspection query will be run)\n  - a GraphQL document containing the schema (.graphql or .gql)\n  - a JSON document containing the schema (as returned by the introspection query)\n  - an importable module with the schema as its default export (either an instance\n    of GraphQLSchema or a JSON object)\n\nOptions:\n\n  --title \u003cstring\u003e       Change the top heading title (default: 'Schema Types')\n  --no-title             Do not print a default title\n  --no-toc               Do not print table of contents\n  --toc-fields \u003clist\u003e    Expand the table of contents for the listed types\n                         (comma-separated) to link to fields within those types\n                         (e.g. --toc-fields \"Query,Mutation,Subscription\") or use\n                         the string \"*\" to link to fields for all types\n  --prologue \u003cstring\u003e    Include custom Markdown after the title\n  --epilogue \u003cstring\u003e    Include custom Markdown after everything else\n  --heading-level \u003cnum\u003e  Heading level to begin at, useful if you are embedding the\n                         output in a document with other sections (default: 1)\n  --update-file \u003cfile\u003e   Markdown document to update (between comment markers) or\n                         create (if the file does not exist)\n  --require \u003cmodule\u003e     If importing the schema from a module, require the specified\n                         module first (useful for e.g. babel-register)\n  --header \u003cname=value\u003e  Additional header(s) to use in GraphQL request\n                         e.g. --header \"Authorization=Bearer ey...\"\n  --version              Print version and exit\n```\n\n### Node API\n\nThe following functions are exported from the `graphql-markdown` module for\nprogrammatic use.\n\n#### loadSchemaJSON(schemaPath: string, options: object)\n\nGiven a string pointing to a GraphQL schema (URL, module, or file path), get the\nresult of the introspection query, suitable for use as input to `renderSchema`.\n\n#### renderSchema(schema: object, options: object)\n\nGiven a schema JSON object (the output of the introspection query, an object\nwith a `__schema` property), render the schema to the console or the provided\n`printer` function.\n\n##### Options\n\n- **`title`**: The title of the document, defaults to “Schema Types”.\n- **`prologue`**: Markdown content to include after the title.\n- **`epilogue`**: Markdown content to include after everything else.\n- **`printer`**: A function to handle each line of output, defaults to\n  `console.log`.\n- **`skipTableOfContents`**: When set, rendering of \"Table of contents\" section\n  is skipped.\n- **`tocFieldTypes`**: An array of type names whose table of contents entry will\n  be expanded to link to individual fields in a nested list. Include the special\n  name `*` in the array to match all types.\n- **`headingLevel`**: The initial level at which to render Markdown headings in\n  the output, defaults to 1. Use this if you are using `updateSchema` to embed\n  the output in a larger document with other sections.\n- **`unknownTypeURL`**: A string or function to determine the URL for linking to\n  types that aren’t found in the schema being rendered. This may be the case if\n  you’re rendering the result of `diffSchema()`, for example. String values will\n  have `#${type.name.toLowerCase()}` appended, and function values will be\n  called with the type object for full control.\n\n#### updateSchema(path: string, schema: object, options: object)\n\nGiven a path to a Markdown document, inject the output of `renderSchema` (with\nthe given schema and options) into the document between the comment markers\n`\u003c!-- START graphql-markdown --\u003e` and `\u003c!-- END graphql-markdown --\u003e`. Returns a\nPromise.\n\nIf the file does not exist, it will be created. If the document is empty, the\nnecessary comment markers will automatically be inserted, but if there is\nexisting content and no comment markers, the Promise will be rejected with an\nerror.\n\n#### diffSchema(oldSchema: object, newSchema: object, options: object)\n\nGiven two schema JSON objects (the results of the introspection query on two\nschemas), return a new schema JSON object containing only the added or updated\ntypes and fields. You can use this to document a schema update, or to document\nthe effects of a schema extension (e.g. `extend type` definitions).\n\n##### Options\n\n- **`processTypeDiff`**: A function to add or modify fields on each type that\n  will be output.\n\n## Output\n\nOutput is optimized for display on GitHub, using GitHub Flavored Markdown. Due\nto the complexity of the tables in the generated document, much of the table\noutput is raw HTML (as allowed by Markdown).\n\n[example]: https://github.com/exogen/graphbrainz/blob/master/docs/types.md\n[graphbrainz]: https://github.com/exogen/graphbrainz\n","funding_links":["https://github.com/sponsors/exogen","https://buymeacoffee.com/mosswood","https://www.buymeacoffee.com/mosswood"],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexogen%2Fgraphql-markdown","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fexogen%2Fgraphql-markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fexogen%2Fgraphql-markdown/lists"}