https://github.com/aschaeffer/mdbook-preprocessor-graphql-playground

A preprocessor for mdbook to add GraphQL playgrounds.
https://github.com/aschaeffer/mdbook-preprocessor-graphql-playground

documentation-generator graphql mdbook mdbook-plugins mdbook-preprocessor

Last synced: 12 days ago
JSON representation

A preprocessor for mdbook to add GraphQL playgrounds.

• Host: GitHub
• URL: https://github.com/aschaeffer/mdbook-preprocessor-graphql-playground
• Owner: aschaeffer
• License: mit
• Created: 2022-09-09T12:21:51.000Z (about 2 years ago)
• Default Branch: main
• Last Pushed: 2024-10-06T21:14:46.000Z (about 1 month ago)
• Last Synced: 2024-10-16T18:38:20.287Z (about 1 month ago)
• Topics: documentation-generator, graphql, mdbook, mdbook-plugins, mdbook-preprocessor
• Language: JavaScript
• Homepage: https://aschaeffer.github.io/mdbook-preprocessor-graphql-playground/
• Size: 1.91 MB
• Stars: 3
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE.md
  • Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

        
# GraphQL Playground for your mdbook

A preprocessor for [mdbook](https://github.com/rust-lang/mdBook) to add a [GraphQL playground](https://github.com/graphql/graphql-playground).

---

[](https://aschaeffer.github.io/mdbook-preprocessor-graphql-playground/)

[![Crate](https://img.shields.io/crates/v/mdbook-preprocessor-graphql-playground.svg)](https://crates.io/crates/mdbook-preprocessor-graphql-playground)

[](https://www.rust-lang.org/)

[](https://github.com/aschaeffer/mdbook-preprocessor-graphql-playground/actions?query=workflow%3ARust)

[]()

[]()

[![downloads](https://img.shields.io/crates/d/mdbook-preprocessor-graphql-playground.svg)](https://crates.io/crates/mdbook-preprocessor-graphql-playground)

---

[![preview](book/src/images/screenshot.png)](book/src/images/screenshot.png)

## Demo

https://aschaeffer.github.io/mdbook-preprocessor-graphql-playground/

## Usage

1. Install `mdbook-preprocessor-graphql-playground`

    ```shell

    cargo install mdbook-preprocessor-graphql-playground

    ```

2. Add to `book.toml`:

    ```toml

    [preprocessor.graphql-playground]

    command = "mdbook-graphql-playground"

    renderer = ["html"]

    

    [output]

    

    [output.html]

    additional-js = ["graphql-playground-react-middleware.js", "graphql-playground.js"]

    additional-css = ["graphql-playground.css"]

    ```

3. Copy assets into the book root directory:

    ```shell

    cp assets/graphql-playground.css 

    cp assets/graphql-playground.js 

    cp assets/graphql-playground-react-middleware.js 

    cp assets/images/* /src/images/

    ```

4. Create a [query file](#query-files)

    ```shell

    mkdir -p /queries/swapi

    nano /queries/swapi/all-planets.query.graphql

    ```

5. Create a [config file](#config-files)

    ```shell

    mkdir /configs

    nano /configs/swapi.json

    ```

6. Embed the GraphQL Playground in your markdown files

    ```

    {{ graphql_playground(config="/configs/swapi.json") }}

    ```

### Query files

* You can have multiple queries

```graphql

query AllPlanetsQuery {

  allPlanets {

    planets {

      name

      diameter

    }

  }

}

```

### Config files

* You can have multiple config files

* You can have multiple tabs, each refers to a query

```json

{

  "title": "The Star Wars API",

  "description": "Explore the star wars API using mdbook-preprocessor-graphql-playground",

  "endpoint": "https://swapi-graphql.netlify.app/.netlify/functions/index",

  "tabs": [

    {

      "name": "All Planets",

      "url": "/queries/swapi/all-planets.query.graphql"

    }

  ]

}

```

### Use a config in the book

1. Embed with the `graphql_playground` function

2. Specify the location of the config file with the `config` parameter

```

{{ graphql_playground(config="/configs/swapi.json") }}

```

### Example

A full example can be found [in this repository](https://github.com/aschaeffer/mdbook-preprocessor-graphql-playground/tree/main/book)