A Gatsby theme to create profile pages and a profiles overview page.


Theme options

Key Default value Description
basePath / Root url for all profiles. Should be changed to /profiles in most cases. basePath is used in Gatsby lifecycle methods to generate individual profile pages and the profiles overview page.
contentPath content/profiles Location of profile MDX files. The filename convention is <slug>.md, e.g. antonio-guterres.md. If you do not set a slug in the frontmatter, the MDX file’s base name, in this example antonio-guterres, is used as slug. contentPath is used to configure plugin gatsby-source-filesystem. Any file in contentPath is part of the GraphQL Mdx collection.
assetPath content/assets Location of avatar images. assetPath is used to configure plugin gatsby-source-filesystem. Any image in assetPath can be linked to a profile by adding it to the frontmatter avatar key via relative path. Avatar images can follow any file name convention you like. The recommended convention is <slug>.{jpg|png}, e.g. antonio-guterres.jpg.
collection profiles The collection option is supplied to the name option of plugin gatsby-source-filesystem for the contentPath definition. This makes it possible to filter File nodes by collection using sourceInstanceName. If you configure this theme more than once in gatsby-config.js, you can use collection to distinguish different profile collections, e.g. collection authors for author profiles and collection speakers for speaker profiles.
postCollection undefined If this option is set, it refers to a collection of posts defined with @undataforum/gatsby-theme-blog. On each profile page, all posts from this collection matching the profile’s slug are displayed.

This example config shows how to configure two separate profiles collections:

// gatsby-config.js
module.exports = {
  plugins: [
      resolve: '@undataforum/gatsby-theme-profiles',
      options: {
        basePath: '/author-profiles',
        contentPath: 'content/author-profiles',
        assetPath: 'content/assets/author-profiles',
        collection: 'author-profiles'
      resolve: '@undataforum/gatsby-theme-profiles',
      options: {
        basePath: '/speaker-profiles',
        contentPath: 'content/speaker-profiles',
        assetPath: 'content/assets/speaker-profiles',
        collection: 'speaker-profiles'

MDX frontmatter

Frontmatter keys for MDX profiles located in contentPath. The YAML type of each key corresponds to the GraphQL type listed in the following section.

Key Required Description
avatar yes Relative path to avatar image located in the assetPath.
honorific no Honorific title, e.g. Her Excellency or His Royal Highness.
firstName yes First name.
lastName yes Last name.
jobtitle no Job title.
organization no Organization.
slug no The default slug is the profile MDX file’s base name. This value overrides the default.
description no The default description for SEO purposes is the first paragraph in a profile MDX file. This value overrrides the default.
roles no One or more roles that a profile can have. This is a YAML list with role keys as values, e.g. 2020-committee-member or 2018-organizer.

GraphQL Profile type

This theme adds GraphQL type Profile which can be queried with profile and allProfile queries. Type Profile makes no assumptions about what the underlying data source is.

Field Type Description
id ID! Gatsby node GUID.
slug ID! Alternative ID used for querying and building the graph.
collection String! Distinguish separate profile collections.
avatar File! If in the future data sources other than MDX are supported, avatar still needs to be of type File!, e.g. downoaded from Contentful to cache. Data sources need to support gatsby-image.
firstName String! firstName can be used to sort profiles alphabetically.
lastName String! lastName can be used to sort profiles alphabetically.
name String! Display name.
honorific String
jobtitle String
organization String
description String
body String! A string representation of the body of the profile page. For MDX pages this is the MDX body.
roles [String!] A role is an identifier that can be used to lookup a role name. A profile can have more than one role.
path String! Path to generated page.


Key Description
title Title of profiles overview page.
description Description page metadata for profiles overview page.
relatedPosts Heading for related posts on profile pages. May contain the {firstName} tag.