Skip to main content
Get up and running with GraphDoc in just a few steps. This guide will walk you through generating your first GraphQL documentation site.

​
Generate from a live endpoint

The fastest way to create documentation is to point GraphDoc at a live GraphQL endpoint.
1

Install GraphDoc

If you haven’t already, install GraphDoc globally:
npm install -g @2fd/graphdoc
Or use npx to run without installing:
npx @2fd/graphdoc --version
2

Generate documentation

Point GraphDoc at your GraphQL endpoint and specify an output directory:
graphdoc -e http://localhost:8080/graphql -o ./docs
The -e flag specifies the endpoint URL, and -o sets the output directory where HTML files will be generated.
3

View your documentation

Open the generated documentation in your browser:
open docs/index.html
Or on Linux:
xdg-open docs/index.html
You’ll see a complete documentation site with all your types, queries, mutations, and subscriptions.
GraphDoc generates static HTML files, so you can host them anywhere—upload to GitHub Pages, Netlify, S3, or any web server.

​
Generate from a schema file

If you have your schema defined in a file, you can generate documentation without a running server. 
graphdoc -s ./schema.graphql -o ./docs
GraphDoc automatically detects the file type based on the extension:
  • .graphql, .gql, .graphqls, .gqls - GraphQL Schema Definition Language
  • .json - GraphQL introspection query result
  • .js - JavaScript module exporting a GraphQL schema
For GraphQL IDL files (.graphql), your schema must be valid and interpretable by graphql-js’s buildSchema function.

​
Using authentication

If your GraphQL endpoint requires authentication, you can pass headers or query parameters: 
graphdoc \
  -e https://api.example.com/graphql \
  -x "Authorization: Bearer YOUR_TOKEN" \
  -o ./docs
Be careful not to commit authentication tokens to version control. Consider using environment variables or configuration files that are git-ignored.

​
Configuration with package.json

For repeated documentation generation, store your configuration in package.json:
1

Add graphdoc configuration

Add a graphdoc section to your package.json:
package.json
{
  "name": "my-api",
  "version": "1.0.0",
  "graphdoc": {
    "endpoint": "http://localhost:8080/graphql",
    "output": "./docs/schema"
  }
}
2

Run GraphDoc

Now you can run GraphDoc without any flags:
graphdoc
GraphDoc will automatically read the configuration from package.json.
3

Add to npm scripts (optional)

Create an npm script for easy documentation generation:
package.json
{
  "scripts": {
    "docs": "graphdoc"
  },
  "graphdoc": {
    "endpoint": "http://localhost:8080/graphql",
    "output": "./docs/schema"
  }
}
Run with:
npm run docs

​
Advanced configuration options

GraphDoc supports many configuration options. Here’s a complete example:
package.json
{
  "name": "my-graphql-api",
  "version": "1.0.0",
  "graphdoc": {
    "endpoint": "http://localhost:8080/graphql",
    "output": "./docs/schema",
    "force": true,
    "verbose": true,
    "baseUrl": "./",
    "plugins": [
      "graphdoc/plugins/default"
    ],
    "data": {
      "title": "My API Documentation",
      "description": "Complete GraphQL API reference"
    }
  }
}
  • endpoint - GraphQL HTTP endpoint URL
  • schemaFile - Path to schema file (alternative to endpoint)
  • output - Output directory for generated files (required)
  • force - Delete output directory if it exists before generating
  • verbose - Print detailed information during generation
  • baseUrl - Base URL for templates (useful for hosting in subdirectories)
  • plugins - Array of plugin paths to use
  • template - Custom template directory path
  • data - Custom data to inject into templates
  • headers - Array of HTTP headers for endpoint requests
  • queries - Array of query parameters for endpoint requests

​
Using custom configuration files

You can use a custom configuration file instead of package.json:
1

Create configuration file

Create a file like graphdoc.config.json:
graphdoc.config.json
{
  "name": "github-api",
  "version": "1.0.0",
  "description": "GitHub GraphQL API",
  "graphdoc": {
    "schemaFile": "./schema.json",
    "output": "./docs",
    "baseUrl": "./"
  }
}
2

Run with config flag

graphdoc -c graphdoc.config.json

​
Force regeneration

By default, GraphDoc will not overwrite an existing output directory. Use the --force flag to regenerate: 
graphdoc -e http://localhost:8080/graphql -o ./docs --force
Or in package.json: 
{
  "graphdoc": {
    "endpoint": "http://localhost:8080/graphql",
    "output": "./docs",
    "force": true
  }
}
The --force flag will delete the entire output directory before generating new documentation. Make sure you don’t have any custom files in that directory that you want to keep.

​
Verbose output

For debugging or to see detailed generation progress, enable verbose mode: 
graphdoc -e http://localhost:8080/graphql -o ./docs --verbose
This will display:
  • Plugins being used
  • Assets being copied
  • Each type/directive being rendered
  • Output directory information
  • Total files generated

​
Common workflows

Development documentation

Generate docs from your local development server:
graphdoc -e http://localhost:4000/graphql -o ./docs -f -v

Production documentation

Use a schema file to avoid hitting production endpoints:
graphdoc -s ./schema.graphql -o ./public/docs

CI/CD pipeline

Generate and deploy docs automatically:
npx @2fd/graphdoc -s ./schema.json -o ./dist/docs -f

Version control

Commit schema file, generate docs on deployment:
"scripts": {
  "predeploy": "graphdoc -s ./schema.json -o ./build/docs"
}

​
Next steps

Now that you’ve generated your first documentation, you can:
  • Customize the output with plugins
  • Create custom templates for unique branding
  • Integrate documentation generation into your CI/CD pipeline
  • Host your documentation on GitHub Pages or other static hosting services
For a complete list of all available command-line options, run:
graphdoc --help

Build docs developers (and LLMs) love

Get started for freeTalk to us