Skip to main content

Getting started

Get started by creating a new site.

Or try GraphQL-Markdown immediately with our demo.

New site​

Requirements​

Node.js version 18.0 or above (which can be checked by running node -v) is required.

info

When installing Node.js, you are recommended to check all checkboxes related to dependencies.

tip

You can use nvm for managing multiple Node.js versions on a single machine installed.

Generate a new site​

Generate a new Docusaurus site using the GraphQL-Markdown template.

The template will automatically be added to your project after you run the command:

shell
npm init docusaurus my-website https://github.com/graphql-markdown/template.git

You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.

The command also installs all necessary dependencies you need to run Docusaurus.

Add a GraphQL schema loader​

See schema loading.

tip

The template comes by default with @graphql-tools/url-loader for remote schemas.

Start your site​

Run the development server:

shell
cd my-website
npm start

The cd command changes the directory you're working with. To work with your newly created Docusaurus site, you'll need to navigate the terminal there.

tip

The npm run doc is a template shortcut for command line document generation npm run docusaurus graphql-to-doc.

The npm run start command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.

Existing site​

Requirements​

  • Node.js version 18.0 or above (which can be checked by running node -v).
    • When installing Node.js, you are recommended to check all checkboxes related to dependencies.
  • Docusaurus instance version 2.0 or above with the docs feature.
  • GraphQL.js version 16.0 or above.

Install the plugin​

Add the @graphql-markdown/docusaurus plugin to your site installation:

shell
npm install @graphql-markdown/docusaurus graphql

Add a GraphQL schema loader​

See schema loading.

Configure the plugin​

See configuration.

Update your documentation​

Build your website:

shell
npm run docusaurus build

OR

Run the documentation generator using CLI:

shell
npm run docusaurus graphql-to-doc

The npm run docusaurus graphql-to-doc command generates MDX files locally from your GraphQL schema. The possible command flags are documented in settings.