Apollopedia

This package is used as the source of truth for Apollo and GraphQL definitions. It also provides a component to highlight key terms in blocks of text and explain what those terms mean in a popover on click.

The terms themselves are maintained as Markdown files within the terms directory. Each term has the following structure:

• The file name is the term that should be highlighted. If the term contains a slash, you'll have to encode it using URL encoding (%2F), so @apollo/gateway would be written as @apollo%2Fgateway.
• The main content of the Markdown file is the definition to display in the popover.
• The file can also includes the following (optional) frontmatter key-value pairs:
  • labels: Categories for terms, for example, "Apollo," (when it's an Apollo-specific term) "GraphQL," "backend," etc.
  • relatedTerms: Related—but not synonymous—terms viewers may be interested in reading about
  • usageInstructions: How to properly use the term, including capitalization, whether or not to use "the", etc.
  • exampleUsage: An example of the term in context
  • businessContext: Business context for Apollonauts' eyes only
  • internalOnly: Whether the term should appear in customer-facing educational resources (including as a popover)
  • learnMore: a URL where readers can learn more about the term
  • learnMoreText: a custom text to display instead of "Learn more about this term."
  • surroundingContextsToAvoid: an array of terms to avoid highlighting the term in the context of (e.g. don't highlight "variable" when found in the context of "environment variable")

These attributes are to be used outside of the popover, for example, in https://www.apollographql.com/docs/resources/graphql-glossary/.

The Markdown format makes it easy to apply formatting and write code blocks within a term's definition. It also provides a boost for maintainers, improving readability when reviewing changes or approving new terms.

Installation

yarn add @apollo/pedia

Popover usage

In its simplest form, the HighlightKeyTerms component exported by the @apollo/pedia package takes some text as its children and automatically highlights key terms within it.

import { HighlightKeyTerms } from "@apollo/pedia";

export const MyComponent = () => {
  return (
    <div>
      <h1>welcome to my website</h1>
      <p>
        <HighlightKeyTerms>
          this is a some text that contains a key term, like subgraph
        </HighlightKeyTerms>
      </p>
    </div>
  );
};

With MDX

If you're using MDX, you can use the component substitution API to automatically highlight key terms that appear anywhere in the page.

import { HighlightKeyTerms } from "@apollo/pedia";

const components = {
  // wrap the children of paragraphs in our highlighter
  p: ({ children }: JSX.IntrinsicElements["p"]) => {
    return (
      <p>
        <HighlightKeyTerms>{children}</HighlightKeyTerms>
      </p>
    );
  },
  // you can wrap other elements too, like list items
  li: ({ children }: JSX.IntrinsicElements["li"]) => {
    return (
      <li>
        <HighlightKeyTerms>{children}</HighlightKeyTerms>
      </li>
    );
  },
};

export const MdxTemplate = () => {
  return <MdxProvider components={components}></MdxProvider>;
};

Term contributions

To update, add, or delete terms, directly edit the .md files in the terms directory. Do not edit the terms.json or raw-terms.json files. The terms.json file is an automatically compiled version of the Markdown files.

Validate changes

To view how your updates look in the popover, you can update example/src/pages/index.js and run pnpm install && pnpm start in the example directory.

Add a changeset

Once you've created your PR with the changes, run yarn changeset add in the root directory to add a changeset that will trigger deployment to your PR.

Request a review

The Apollo docs team is a code owner for the terms directory and will be automatically pinged on any PRs that touch files in this directory. To expedite a review, you can ping #inbox-docs with a link to the PR. The docs team will loop in any other teams needed for review.

Deploy and update

Once your PR is merged, an automated "Version Packages" PR is created. Once you merge that PR, the new version is deployed to npm. Don't forget to update the @apollo/pedia version number in any dependent repositories.