{"id":13704867,"url":"https://github.com/zhouzi/docusaurus-graphql-plugin","last_synced_at":"2025-04-12T20:33:00.741Z","repository":{"id":40345648,"uuid":"342019645","full_name":"zhouzi/docusaurus-graphql-plugin","owner":"zhouzi","description":"Docusaurus plugin generating Markdown documentation from a GraphQL schema.","archived":false,"fork":false,"pushed_at":"2023-12-06T18:43:43.000Z","size":3927,"stargazers_count":25,"open_issues_count":5,"forks_count":9,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-08T10:02:29.183Z","etag":null,"topics":["documentation","docusaurus","generator","graphql","markdown","plugin"],"latest_commit_sha":null,"homepage":"https://gabinaureche.com/docusaurus-graphql-plugin/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zhouzi.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-02-24T19:59:16.000Z","updated_at":"2024-12-23T18:56:33.000Z","dependencies_parsed_at":"2024-01-12T21:17:16.976Z","dependency_job_id":"27cf6b04-be97-4441-bd57-9bb1f561738e","html_url":"https://github.com/zhouzi/docusaurus-graphql-plugin","commit_stats":{"total_commits":80,"total_committers":5,"mean_commits":16.0,"dds":0.07499999999999996,"last_synced_commit":"b8920edd09a370cb0cc1297f36dff9be2bdf4a7c"},"previous_names":["zhouzi/docusaurus-plugin-content-graphql"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhouzi%2Fdocusaurus-graphql-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhouzi%2Fdocusaurus-graphql-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhouzi%2Fdocusaurus-graphql-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zhouzi%2Fdocusaurus-graphql-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zhouzi","download_url":"https://codeload.github.com/zhouzi/docusaurus-graphql-plugin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248630439,"owners_count":21136437,"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":["documentation","docusaurus","generator","graphql","markdown","plugin"],"created_at":"2024-08-02T22:00:21.804Z","updated_at":"2025-04-12T20:33:00.407Z","avatar_url":"https://github.com/zhouzi.png","language":"TypeScript","readme":"# docusaurus-graphql-plugin\n\nDocusaurus plugin generating Markdown documentation from a GraphQL schema.\n\n## Motivation\n\nDocumentation is at the heart of GraphQL. Its core features makes up for great self documented APIs.\nFrom a consumer's perspective, it usually comes in the form of types, clear expectations and precise error messages.\nThe standards also make it easy to build playgrounds, which come with many implementations.\nThe typical playground offers a way to browse the API and learn more about its queries and mutations.\n\nBut while playgrounds are a great way to play around with an API, they are not necessarily the best first-time experience.\nThis is especially true for GraphQL which may look a bit alien compared to the traditional, popular and mature REST approach.\nSo a playground alone might not be enough, especially for public APIs targeted to teams with varying backgrounds and technologies.\n\nThis is the gap that this plugin tries to fill.\nIts goal is to generate documentation that is easy to browse and share with minimum prior experience.\nTo reach this goal, it takes most of its ideas from [GitHub's GraphQL API documentation](https://docs.github.com/en/graphql).\n\n## Usage\n\n### Installation\n\n1. In an existing Docusaurus project, install the plugin:\n\n```\nyarn add docusaurus-graphql-plugin\n```\n\n2. Add the plugin to your `docusaurus.config.js` file:\n\n```js\nmodule.exports = {\n  plugins: [\n    [\n      \"docusaurus-graphql-plugin\",\n      {\n        // can be a path, a glob or an URL\n        schema: \"schema.graphql\",\n      },\n    ],\n  ],\n};\n```\n\n3. Run the command `npx docusaurus docs:generate:graphql`\n\n4. The command will have generated files that you can now add to your `sidebars.js`:\n\n```js\nmodules.exports = {\n  docs: {\n    API: [\n      \"api/queries\",\n      \"api/mutations\",\n      \"api/objects\",\n      \"api/interfaces\",\n      \"api/enums\",\n      \"api/unions\",\n      \"api/inputObjects\",\n      \"api/scalars\",\n    ],\n  },\n};\n```\n\n5. You can now run `yarn start` to serve your documentation\n\n### Options\n\n#### `id`\n\nThis option is common to docusaurus plugins and can be used to differentiate multiple instance of the plugin.\nFor example:\n\n```js\nmodule.exports = {\n  plugins: [\n    [\n      \"docusaurus-graphql-plugin\",\n      {\n        id: \"first-api\",\n        schema: \"first-api.graphql\",\n        // it's important that routeBasePath has a different\n        // value for each instance of the plugin\n        routeBasePath: \"/docs/first-api\",\n      },\n    ],\n    [\n      \"docusaurus-graphql-plugin\",\n      {\n        id: \"second-api\",\n        schema: \"second-api.graphql\",\n        // it's important that routeBasePath has a different\n        // value for each instance of the plugin\n        routeBasePath: \"/docs/second-api\",\n      },\n    ],\n  ],\n};\n```\n\nWith the configuration above you would end up with two different commands:\n\n- `docs:generate:graphql:first-api`\n- `docs:generate:graphql:second-api`\n\n#### `schema`\n\nCan be a path, a glob or an URL used to load your GraphQL schema.\n\n#### `routeBasePath`\n\n**Defaults:** `/docs/api/`\n\nThis option can be used to customize the output folder and thus the GraphQL docs' path.\n\nFor example if you want the API docs to be served over `/docs/api-reference/` instead of `/docs/api/`, you can change this option to `/docs/api-reference/`. Note that you can also have more levels to the path, e.g `/docs/reference/api/`.\n\n```js\nmodule.exports = {\n  plugins: [\n    [\n      \"docusaurus-graphql-plugin\",\n      {\n        schema: \"schema.graphql\",\n        routeBasePath: \"/docs/api-reference/\",\n      },\n    ],\n  ],\n};\n```\n\n#### `sidebar`\n\nThis option can be used to specify sidebar metadata when using auto-generated sidebar.\n\n```js\nmodule.exports = {\n  plugins: [\n    [\n      \"docusaurus-graphql-plugin\",\n      {\n        schema: \"schema.graphql\",\n        sidebar: {\n          label: \"My Awesome Schema\",\n          position: 1,\n        },\n      },\n    ],\n  ],\n};\n```\n\nThe configuration above will create a [`_category_.json`](https://docusaurus.io/docs/sidebar#autogenerated-sidebar-metadatas) file in the `routeBasePath` looking like this :\n\n```json\n{\n  \"label\": \"My Awesome Schema\",\n  \"position\": 1\n}\n```\n","funding_links":[],"categories":["Plugins","TypeScript"],"sub_categories":["Data sources"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhouzi%2Fdocusaurus-graphql-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzhouzi%2Fdocusaurus-graphql-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzhouzi%2Fdocusaurus-graphql-plugin/lists"}