Polen

Appearance

Examples ​

Introduction ​

Polen automatically discovers GraphQL examples from your examples directory and displays them as interactive code blocks on your home page.

When examples are present the navbar will display an examples link.

Routes ​

  • /examples/{example-name} – Individual example pages
  • /examples – Examples overview if index present or just redirection to your first example

Supplying Your Examples ​

File Convention ​

Unversioned Examples ​

Place .graphql files in the examples directory:

examples/
├── get-user.graphql
├── create-post.graphql
└── search-products.graphql

Versioned Examples ​

When using multiple schema versions, you can author version-specific examples.

  • Use version identifier in extensions for version-specific examples
  • Use base .graphql file as fallback for versions without specific files
  • Versioned examples display a client-side version picker in the UI, allowing users to switch between versions

Example:

examples/
├── get-user.1.graphql
├── get-user.2.graphql
├── get-user.3.graphql
├── create-post.1.graphql
├── create-post.graphql        # Serves as default for versions 2 and 3
└── search-products.graphql    # Unversioned (applies to all versions)

Index ​

You can display arbirary content on the index page by adding an index.md file in your examples directory.

Example:

examples/
├── index.md              # Optional: Custom overview content
├── ...
└── search-products.graphql

Descriptions ​

Each example can have an optional description that appears above the GraphQL code. Add a markdown file with the same name as your example:

examples/
├── get-user.graphql      # The example query
├── get-user.md           # Description for this example
├── create-post.graphql
├── create-post.mdx       # MDX also supported for rich content
└── search-products.graphql

Description features:

  • Markdown/MDX support: Full markdown formatting and MDX components
  • Automatic discovery: Files matching <example-name>.md or <example-name>.mdx
  • Rendered above code: Descriptions appear before the GraphQL example
  • Same rendering pipeline: Uses Polen's standard markdown processing