Customization

There are several ways to customize the A11ystack Gatsby frontend for your needs.

Gatsby Config

The Gatsby themes have a bunch of options that can be set in /gatsby-config.js.

export const plugins = [
  {
    resolve: `@municipio/gatsby-theme-basic`,
    options: {
      basePath: __dirname,
      fragmentsDir: `${__dirname}/src/fragments`,
      i18next: {
        defaultLanguage: "en",
        languages: ["en", "sv"],
      },
      wp: {
        url: process.env.GATSBY_WORDPRESS_URL,
        nodesPerFetch: Number(process.env.WORDPRESS_NODES_PER_FETCH),
        contentTypes: {
          post: {},
          page: {},
        },
      },
      search: {
        paths: ["/search", "/sv/sok"],
      },
    },
  },
];

• basePath: This is just a way to pass the root dir path to the plugin, so it should always be set to __dirname. Required.
• fragmentsDir: The location of your GraphQL fragments. You probably want to set this to `${__dirname}/src/fragments` in most situations. Required.
• i18next.defaultLanguage: Fallback languages for i18next. Default is "en".
• i18next.languages: Available localizations. Default is ["en"].
• wp.url: URL to Wordpress backend iwthout trailing slash, e.g. "https://cms.example.com". Required.
• wp.nodesPerFetch: Number of posts to fetch per paginated GraphQL request. Fetching too many per request may cause timeout errors, but it’s generally faster. Default is 100.
• wp.contentTypes: Content types to include and overrides for each. Default is { post: {}, page: {} }, which fetches just posts and pages but without overrides. To exclude one of them, set it to false instead of an object.
• search.paths: A search page will be generated at each of these paths, so you’d want to add one per language, or skip it if your don’t want a search page. Default is [], i.e. no generated search page.

Theme provider

The themes use many components from the @whitespace/components library. The Gatsby app is wrapped in a ThemeProvider from @whitespace/components, which means that most of those components can be customized without having to replace them. In the starters, there is a file /src/theme/index.js that is used for this purpose. The default export of that file is fed to ThemeProvider.

ThemeProvider does two things with those values:

1. It passes properties on the second level as default props to the components defined on the first level.
2. It converts number and string values into custom CSS properties (CSS variables), as described below.

Example:

// /src/theme/index.js

export default {
  accordion: {
    showExpandAll: true,
    button: {
      default: {
        background: "#334455",
      },
      hover: {
        background: "#334455",
      },
    },
  },
};

This will pass the properties on the second level (showExpandAll and button) as default values props to the Accordion component, i.e.

<Accordion
  showExpandAll={true}
  button={{
    default: {
      background: "#334455",
    },
    hover: {
      background: "#445566",
    },
  }}
/>

It will also set these CSS variables:

:root {
  --accordion-button-background: #334455;
  --accordion-button-hover-background: #445566;
}

The parent path for each string (and number) value is concatenated and converted to kebab case. Note that any default keys are skipped in this process.

Shadowing

Components that are provided by the themes can be shadowed, as described here. Shadowing should be avoided as much as possible since it severs the connection to the theme and there would be no automatic way of knowing if the shadowed component changes in the future.

CSS variables

As described above, custom CSS properties can be set via the ThemeProvider. It’s of course also possible to define them in CSS files and that is sometimes preferrable. You should create a file inside the /src/theme folder, name it after the component you are targeting and suffix it with .props.css, e.g. /src/theme/Accordion.props.css. Then import it inside /src/theme/index.js.

Fragments

Almost all GraphQL queries that are sent to Wordpress use GraphQL fragments. They are usually located in /src/fragments. Those files are automatically parsed by Gatsby and the fragments are extracted. Edit them if you want to change what data is fetched from Wordpress.

Static files

Icons should be placed inside /static/icons. The Icon and RoundIcon components from @whitespace/components will look here for icons by default.

Locales

String translations must also be incliuded in your project. The themes don’t provide any translations on their own, but there are a bunch of default ones for English in the Gatsby starters.

Locales should defined using yml files inside /locales, e.g. /locales/en.yml.