GithubHelp home page GithubHelp logo

graphql-markdown / graphql-markdown Goto Github PK

View Code? Open in Web Editor NEW
129.0 1.0 26.0 13.58 MB

Flexible GraphQL Documentation Generator (Markdown)

Home Page: https://graphql-markdown.dev

License: MIT License

JavaScript 9.02% Shell 0.19% Earthly 1.01% CSS 1.43% Dockerfile 0.79% TypeScript 87.55%
graphql graphql-schema documentation generator documentation-generator docusaurus markdown gql graphql-markdown graphql-config

graphql-markdown's Introduction

GraphQL-Markdown

Flexible documentation for GraphQL schemas

Latest Version GitHub License Buy us a tree Commitizen friendly

This plugin generates Markdown pages from a GraphQL schema for Docusaurus docs feature.

Installation

graphql package is a peer-dependency, and it should be installed separately.

npm install @graphql-markdown/docusaurus graphql

Add @graphql-markdown/docusaurus to your site's docusaurus.config.js plugins option:

module.exports = {
  // ...
  plugins: ["@graphql-markdown/docusaurus"],
};

Usage

The plugin adds a new command graphql-to-doc to the Docusaurus CLI.

npx docusaurus graphql-to-doc

Command line options are described in the documentation settings page.

Configuration

See documentation configuration page.

Troubleshooting

See documentation troubleshooting page.

License

GraphQL-Markdown packages are 100% free and open-source, under the MIT license.

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest youโ€™ll be creating employment for local families and restoring wildlife habitats.

Contributions

Contributions, issues and feature requests are very welcome. If you are using this package and fixed a bug for yourself, please consider submitting a PR!

graphql-markdown's People

Contributors

carolstran avatar chmanie avatar coder2034 avatar davidyaha avatar dependabot[bot] avatar edno avatar elias-pap avatar graphql-markdown-bot avatar guihash avatar jakxz avatar jineshshah36 avatar jlndk avatar jocrau avatar lauzierj avatar ljiang-ti avatar melvey avatar mimo84 avatar renovate[bot] avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar

graphql-markdown's Issues

windows / links with backslashes

Hey there,

all the cross-links are wrong inside the mdx-files if I run graphql-markdown at windows 10

grafik

and than the browser converts it to ...//...
grafik

after click you got a
grafik

thanks!!

Add support for external file config

Is your feature request related to a problem? Please describe.
There are several cases when several schema documentations need to be generated.
The current workaround is to use CLI parameters, however this can quickly become tedious to maintain.

Describe the solution you'd like
Using external config file will make easier to maintain several configurations. And supporting JS files would even allow sharing configuration between config.
The config resolution will be prioritized as following (starting by highest priority):

  1. CLI parameters
  2. CLI parameter config referring to external config file ๐Ÿ†•
  3. Plugin options in Docusaurus config file
  4. config plugin option in Docusaurus config file ๐Ÿ†•

The config file will respect the current plugin config structure.

GraphQL package as peer dependency

GraphQL package as peer dependency to prevent package version conflict

"peerDependencies": {
    "graphql": "^14.0.0 || ^15.0.0 || ^16.0.0"
  },

windows / Unable to find any GraphQL type definitions

Hi there,

at Windows 10 I got every second time (after delete following file) the error:

"Error: 
      Unable to find any GraphQL type definitions for the following pointers:
        
          - C:\Users\xxx\AppData\Local\Temp\@edno\docusaurus2-graphql-doc-generator\schema.graphql
          
    at prepareResult (D:\workspace\docs\node_modules\@graphql-tools\load\index.js:537:15)
    at loadTypedefs (D:\workspace\docs\node_modules\@graphql-tools\load\index.js:503:12)
    at processTicksAndRejections (internal/process/task_queues.js:93:5)
    at async loadSchema (D:\workspace\docs\node_modules\@graphql-tools\load\index.js:587:21)
    at async checkSchemaChanges (D:\workspace\docs\node_modules\@edno\docusaurus2-graphql-doc-generator\src\lib\diff.js:41:20)
    at async generateDocFromSchema (D:\workspace\docs\node_modules\@edno\docusaurus2-graphql-doc-generator\src\lib\generator.js:33
:22)
    at async Command.<anonymous> (D:\workspace\docs\node_modules\@edno\docusaurus2-graphql-doc-generator\src\index.js:62:11)
"

But the file is there! @ C:\Users\xxx\AppData\Local\Temp@edno\docusaurus2-graphql-doc-generator\schema.graphql
after deleting this file it works again for one time

maybe using the folder .docusaurus inside this project?

thx!

greetings
crazyx13th

Cannot load the sidebar on fresh install

Hello,

I'm new to docusaurus so maybe this is obvious but on a fresh install I'm getting this error while trying to load

Error: Bad sidebars file.
These sidebar document ids do not exist:
- swapi/schema,

Available document ids=
- swapi
- swapi/directives/deprecated
- swapi/directives/include
- swapi/directives/skip
- swapi/directives/specified-by
- swapi/enums/account-billing-types
...

Any pointers?

Use npm instead of yarn

The project currently uses Yarn v1, which does not provide any significant benefits compared to the latest version of npm.
However, as 3rd party tool, it creates extra overhead for the devx. Thus, switching to npm will improve devx, and this will also provides better level of integration with NodeJS 3rd party devx tooling.

Provide/disable date and other options

Is there a way of disabling the generated on date for the schema docs front page or providing fixed info instead using an option?
The date format is also fixed and not one we tend to use in the UK, so depending upon your solution you may wish to address that issue for foreign audiences too :)

Force doc generation

Add flag -f, --force in CLI for forcing doc generation even if no changes detected.

Smoke tests broken

Smoke tests are broken due to Error: Image static/assets/images/grouping_example.png used in docs/README.md not found.

Possible fix: remove the image reference from README.md and replace it with a demo link.

Can't create PR for graphql-markdown project

Describe the bug
I want to submit a PR for this project. I've created a separate branch and have tried to push my branch up but running
into permission issues:

ERROR: Permission to edno/graphql-markdown.git denied to coder2034.
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

Query arguments with default value `0` do not show in generated markdown

Describe the bug

When generating markdown, if a query contains a default argument value of 0 (type is Int), it does not show in the result.

To Reproduce

If applicable, add an extract of the GraphQL schema.

type Query {
  search(
    skip: Int = 0
  ): Int!
}
  • Docusaurus configuration

If applicable, add an extract of the Docusaurus configuration.

Expected behavior

Argument default 0 appears in docs.

Screenshots

image

Additional context

Seems like this is a non-issue in 1.2.2 version but appears after that.

1.3.0 (latest at time of writing) does not include the lib directory

Describe the bug
Error reports as Error: Cannot find module './lib/generator', but really its just exporting one file in the npm package.

image

To Reproduce
It should be universally error producing if this version is installed, I would assume.

  • Docusaurus configuration
    Should not matter

Expected behavior
To have the entire package be installed

Screenshots
Above.

Additional context
Likely suspect is here: https://github.com/edno/graphql-markdown/blob/f3ef0f47c35238a44966e8350ca2927ea630a029/package.json#L63-L65

Standardise commit messages

Is your feature request related to a problem? Please describe.
Help contributors write good commit messages, adhering to the conventional commits format.

Describe the solution you'd like
Add commitizen as a dev dependency and as a prepare-commit-msg husky hook.
Optionally we can also spice things up by using cz-emoji commitizen adapter.

Comments are not being printed out

Describe the bug
Perhaps I misunderstand how comments are treated, so sorry for a confusion if so.

I have a schema with # comment style comments, and expect it to be shown in .mdx file. Instead I get No description

EDIT if I style my comment as

"""
test
"""

it is getting printed out. So why would """ and # would be treated differently and is there a way to make them to produce the same mdx content?

To Reproduce
Run npx docusaurus graphql-to-doc

  • GraphQL schema

If applicable, add an extract of the GraphQL schema.

type Query {
  # test
  foo: Foo
}

  • Docusaurus configuration

If applicable, add an extract of the Docusaurus configuration.

Expected behavior
The foo.mdx file should have test as a description.

Screenshots
If applicable, add screenshots to help explain your problem.

Additional context
Add any other context about the problem here.

What's the purpose of this?

Hey, nice project you have! I'm curious what's the motivation behind it.
As far as I can see, it takes the schema and renders it differently.
What's the use case behind this? Why is the schema not enough?
Awesome work!

Invalid MDX when deprecation reason contains curly braces

Describe the bug

When the deprecation reason contains certain characters like curly braces, the generated MDX document is invalid as the rendered string isn't escaped.

To Reproduce

Use a schema with a deprecated field. The deprecation reason contains curly braces (see example below)

  • GraphQL schema
type Foo {
  oldName: String @deprecated(reason: "Use Foo { newName } instead.")
  newName: String
}
  • Screenshots
Docusaurus Node/SSR could not render static page with path "/graphql/objects/foo" because of following error:

ReferenceError: newName is not defined
    at MDXContent (main:10784:8599)
    at d (main:81641:498)
    at bb (main:81644:16)
    at a.b.render (main:81650:43)
    at a.b.read (main:81649:83)
    at Object.exports.renderToString (main:81660:138)
    at doRender (main:2021:356)
    at async serverEntry_render (main:2020:294)

Expected behavior

The generated MDX file is valid and can be compiled by docusaurus.

Improve code coverage

Code coverage dropped below 80%, this introduces risk when accepting contributions.

Code coverage should be increased to 85% as minimum.

Add coverage quality gate from Sonarcloud.

Label documentation

We need to know what are the changes in the documentation compared to a live version: update, new, deprecated.

Using graphql-inspector for comparing local schema against a ref schema, we can get such information when generating the documentation and placing the correct label N, U, D.

This requires to add a custom theme.

Use autogenerated sidebar

Docusaurus supports auto-generated sidebar:

module.exports = {
  schemaSidebar: [
    { type: "doc", id: "api/schema" },
    {
      type: "autogenerated",
      dirName: "api",
    },
  ],
};

Using this feature would remove the complexity to generate the sidebar, and also the potential failures while booting the server.

TypeError: Cannot read property 'groups' of null

Describe the bug

an error "TypeError: Cannot read property 'groups' of null" occured when I runed docusaurus graphql-to-doc

To Reproduce

  • Docusaurus configuration
    If applicable, add an extract of the Docusaurus configuration.
plugins: [
 [
    require.resolve("@edno/docusaurus2-graphql-doc-generator"),
    {
      id: 'admin',
      schema: "<my private url>",
      rootPath: "./docs/graphql",
      baseURL: "admin",
      homepage: "./docs/graphql/admin/index.md",
    },
  ],
  [
    require.resolve("@edno/docusaurus2-graphql-doc-generator"),
    {
      id: 'storeadmin',
      schema: "<my private url>",
      rootPath: "./docs/graphql",
      baseURL: "storeadmin",
      homepage: "./docs/graphql/storeadmin/index.md",
    },
  ],
  [
    require.resolve("@edno/docusaurus2-graphql-doc-generator"),
    {
      id: 'storefront',
      schema: "<my private url>",
      rootPath: "./docs/graphql",
      baseURL: "storefront",
      homepage: "./docs/graphql/storefront/index.md",
    },
  ]
]

Expected behavior
A clear and concise description of what you expected to happen.

Screenshots

TypeError: Cannot read property 'groups' of null
    at Renderer.renderTypeEntities (D:\Projects\booking-app\docusaurus\node_modules\@edno\docusaurus2-graphql-doc-generator\src\lib\renderer.js:60:35)
    at async Promise.all (index 0)
    at async Renderer.renderRootTypes (D:\Projects\booking-app\docusaurus\node_modules\@edno\docusaurus2-graphql-doc-generator\src\lib\renderer.js:40:15)
    at async Promise.all (index 0)
    at async generateDocFromSchema (D:\Projects\booking-app\docusaurus\node_modules\@edno\docusaurus2-graphql-doc-generator\src\lib\generator.js:41:19)
    at async Command.<anonymous> (D:\Projects\booking-app\docusaurus\node_modules\@edno\docusaurus2-graphql-doc-generator\src\index.js:62:11)

Additional context

  • Windows 10
  • Powershell Core 7
  • Node.js v14.17.4
  • Yarn v1.22.11
  • Docusaurus v2-beta.4

Cannot read property of groups of null at Renderer.renderTypeEntities

(node:4452) UnhandledPromiseRejectionWarning: TypeError: Cannot read property 'groups' of null
    at Renderer.renderTypeEntities (C:\<dir>\node_modules\@edno\docusaurus2-graphql-doc-generator\src\lib\renderer.js:59:35)
    at async Promise.all (index 3)
    at async Renderer.renderRootTypes (C:\<dir>\node_modules\@edno\docusaurus2-graphql-doc-generator\src\lib\renderer.js:37:7)
    at async Promise.all (index 0)
(Use `node --trace-warnings ...` to show where the warning was created)
(node:4452) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). 
To terminate the node process on unhandled promise rejection, use the CLI flag `--unhandled-rejections=strict` (see https://nodejs.org/api/cli.html#cli_unhandled_rejections_mode). (rejection id: 1)
(node:4452) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.

I run a second time because it errored out, and it says there are no changes, so I have to remove the schema and hash from temp directory and then run again, so that was not friendly either.

Vresions:

    "@docusaurus/core": "2.0.0-alpha.75",
    "@docusaurus/preset-classic": "2.0.0-alpha.75",
    "@edno/docusaurus2-graphql-doc-generator": "^1.1.0",

Config (docusaurus.config.js):

/** @type {import('@docusaurus/types').DocusaurusConfig} */
module.exports = {
  title: 'My Site',
  tagline: 'Dinosaurs are cool',
  url: 'https://your-docusaurus-test-site.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  organizationName: 'facebook', // Usually your GitHub org/user name.
  projectName: 'docusaurus', // Usually your repo name.
  themeConfig: {
    navbar: {
      title: 'My Site',
      logo: {
        alt: 'My Site Logo',
        src: 'img/logo.svg',
      },
      items: [
        {
          to: "/docs/api",
          label: "API",
          position: "left",
        },
        {
          type: 'doc',
          docId: 'intro',
          position: 'left',
          label: 'Tutorial',
        },
        {to: '/blog', label: 'Blog', position: 'left'},
        {
          href: 'https://github.com/facebook/docusaurus',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },
    footer: {
      style: 'dark',
      links: [
        {
          title: 'Docs',
          items: [
            {
              label: 'Tutorial',
              to: '/docs/intro',
            },
          ],
        },
        {
          title: 'Community',
          items: [
            {
              label: 'Stack Overflow',
              href: 'https://stackoverflow.com/questions/tagged/docusaurus',
            },
            {
              label: 'Discord',
              href: 'https://discordapp.com/invite/docusaurus',
            },
            {
              label: 'Twitter',
              href: 'https://twitter.com/docusaurus',
            },
          ],
        },
        {
          title: 'More',
          items: [
            {
              label: 'Blog',
              to: '/blog',
            },
            {
              label: 'GitHub',
              href: 'https://github.com/facebook/docusaurus',
            },
          ],
        },
      ],
      copyright: `Copyright ยฉ ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
    },
  },
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          // Please change this to your repo.
          editUrl:
            'https://github.com/facebook/docusaurus/edit/master/website/',
        },
        blog: {
          showReadingTime: true,
          // Please change this to your repo.
          editUrl:
            'https://github.com/facebook/docusaurus/edit/master/website/blog/',
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      },
    ],
  ],
  plugins: [
    [
      require.resolve("@edno/docusaurus2-graphql-doc-generator"),
      {
        schema: "https://<my-endpoint>.aws.cloud.dgraph.io/graphql",
        rootPath: "./docs", // docs will be generated under './docs/api' (rootPath/baseURL)
        baseURL: "api",
        homepage: "./docs/api.md",
        tmpDir: "./schemaDiff"
      },
    ],
  ]
};

Note: The <vars> are not actual, just placholders for my actual values.

Allow for more than one instance of graphql-doc-generator in docusaurus.config

Is your feature request related to a problem? Please describe.

If you have more than one doc-generator defined, it will only use the first one found.

Describe the solution you'd like

I'd like to be able to define several graphql doc generators, and this seems to be in line with how plugins are defined generally in docusaurus.

Describe alternatives you've considered

A workaround would be to define all configs in command line parameters instead, but this is less than ideal.

You can also comment lines of code in and out and run the command several times. Even less ideal.

Additional context

Link to where Docusaurus explains plugins are all multi instance: https://docusaurus.io/docs/using-plugins#multi-instance-plugins-and-plugin-ids

Allow disabling pagination buttons (next and previous)

Is your feature request related to a problem? Please describe.
API documentation does not need pagination buttons, as navigation is mostly done through sidebar, doc hyperlinks and search.

Describe the solution you'd like
Add configuration option to disable the pagination Next and Previous.

Describe alternatives you've considered
n/a

Additional context
Doc: https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#pagination_next

Inline style generates Docusaurus parsing error

The issue is related to Docusaurus MDX parser that does not like inline style definition when running on production mode:

Parsing error

### Specification<a className="link" style={{fontSize:'1.5em', paddingLeft:'4px'}} target="\_blank" href="https://www.w3.org/Protocols/rfc822/" title="Specified by https://www.w3.org/Protocols/rfc822/">โŽ˜</a>

Parsing success

export const specifiedByLinkCss = { fontSize:'1.5em', paddingLeft:'4px' };

### Specification<a className="link" style={specifiedByLinkCss} target="\_blank" href="https://www.w3.org/Protocols/rfc822/" title="Specified by https://www.w3.org/Protocols/rfc822/">โŽ˜</a>

Add CONTRIBUTION.md

Add guidelines for contributing to the project:

  • fork
  • use Earthly for checks
  • code structure
  • tests
  • examples

Make prettier an optional dependency

prettier is used for prettifying generated output. However, this is not really a must-have since the output is not aimed to be consumed raw, but it is instead formatted by Docusaurus.

Making prettier an optional or peer dependency, or not a dependency at all, would provide the following benefits:

  • smaller package footprint once installed
  • one less hard dependency to maintain
  • smaller generated files (but maybe not significant in most of the cases)
  "peerDependencies": {
    "prettier": "^2.4.1",
  },
  "peerDependenciesMeta": {
    "prettier": {
      "optional": true
    }
  }

Arguments type link not working

When generating the pages it seems that the link in the "Arguments" section ignores the rootURL from the options generating a wrong URL. For example the link to a type following the example in the readme should be something like:

### Arguments

#### `version` ([`Int!`](/docs/swapi/scalars/int))

instead generates:

### Arguments

#### `version` ([`Int!`](/swapi/scalars/int))

Input description missing in Mutation document

Input description is not populated when generating the mutation documentation

---
id: remove-entity
title: removeEntity
---

Remove an Entity.

\```graphql
removeEntity(
  input: RemoveEntityInput!
): RemoveEntityResponse!
\```

### Arguments

#### `input` ([RemoveEntityInput!](/docs/api/inputs/remove-entity-input))

### Type

#### [`RemoveEntityResponse`](/docs/api/objects/remove-entity-response)

A Remove Entity Response.

Schema definition:

{
 ...
  """A Remove Entity Input."""
  input RemoveEntityInput {
    """The ID of the Entity."""
    id: ID!

    """The type of the Entity."""
    type: EntityType!
  }
}

Missing `generated.md` file

Describe the bug
Missing generated.md in assets directory

To Reproduce
Do not provide a homepage in the plugin configuration
An error is displayed:

Error: ENOENT: no such file or directory, copyfile '/Users/guihash/api-docs/node_modules/@edno/docusaurus2-graphql-doc-generator/assets/generated.md' -> 'docs/api-reference/generated.md'
  • Docusaurus configuration
module.exports = {
  // ...
  plugins: [
    [
      '@edno/docusaurus2-graphql-doc-generator',,
      {
        schema: "./schema/swapi.graphql",
        rootPath: "./docs", // docs will be generated under './docs/swapi' (rootPath/baseURL)
        baseURL: "swapi",
      },
    ],
  ],
};

Expected behavior
Find the generated.md in the assets directory

Additional context
The file seems to have disappeared between version 1.5.1 and 1.5.3
version 1.5.1
version 1.5.3

Extend existing doc plugin?

Hi and thanks for working on this interesting plugin.

Don't hesitate to submit it to our community docs so users can more easily find it.

One suggestion I could make is, instead of generating the md docs with the CLI, maybe you could extend the docs plugin so that it creates the md files just before reading the md files?

You may find this interesting to try:
facebook/docusaurus#4138 (comment)

Not sure it would be more convenient than a cli though, but can be worth giving it a try

Hyperlinks do not respect docRoot

Changing the docs base url from / to /docs, it's took in consideration only when generating the sidebar because explicitly passed into the config - but not in the hyperlinks id generation

Move generated documentation to separate repo

Generated documentation hosted in the source repo does not provide any value for contributors, and it can be a source of confusion.

Tasks:

  • Create a new graphql-markdown.github.io (see documentation)
  • Update docusaurus settings for using / as base url
  • Regenerate the documentation with the new settings
  • Push the doc to the new repo
  • Update links in package repo and demo repo

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.