VAD VAR Workshop Docs

This repo contains the site code for IBM Ecosystem partner content (primarily our Value-Added Distributors and Value-Added Resellers) to build experiential sales skills with various IBM products.

To see the content itself visit: https://vest.buildlab.cloud/

Built using:

• Next.js
• Velite
• TypeScript
• MDX
• Carbon Design System

Getting started

Before installing any dependencies ensure you have the proper prerequisites installed:

• npm (recommended minimum of v9.0.0)
• node (v18.18.0 is a required minimum with this version of Gatsby)

To get up and running locally the first step is to run:

npm ci

After this, you can run:

npm run dev

This will start the development server at http://localhost:3000.

Note: The current version of @carbon/react seems to not support TypeScript types out of the box for all components.

Linting

Linting has been added via ESLint. To lint code file run:

npm run lint

MDX linting is also available too. To lint content files run:

npm run lint:md

Building static pages

To build the site as static pages you can run:

npm run build

This creates the actual static pages of the site under the /out directory at the root. To serve these pages feel free to use a Python HTTP test server or just run:

npm run serve

Using the supplied serve command will start hosting the site locally at http://localhost:3000.

Build static pages with local assets

By default, the build command will replace all image source references with their remote counterparts in the main branch of the repo. This is done to keep the static build size smaller. To instead include the local assets in the build run:

npm run build:local

You can then use the serve command to verify.

Deployment

Deployment of the static content is handled via GitHub Actions. On a merge to the main branch, a workflow is triggered that will build the static pages and then deploy them as a static site via GitHub Pages.

How content is parsed

Content for the docs is stored as .md files in the /content directory. URLs for each of the files in the documentation are built as a mirror of the file structure within the directory. README.md files are interpreted as the index page of the directory.

To extend functionality the files are parsed using MDX instead of Markdown. This allows for the inclusion of JSX elements/React components if wanted. Standard Markdown syntax is still applicable but any inclusion of HTML tags should instead be using JSX tags.

Note: any inclusion of text that may be misinterpreted as JSX could cause an error when building pages. Be sure to escape any >,<, {, or } characters in text if not used as JSX.

Various plugins to extend functionality further are available via remark and rehype. Custom plugins can also be written through the use of the unified family of libraries as well.

Frontmatter data

Frontmatter data is supported out of the box with gatsby-plugin-mdx. For use in this site, it is always optional for each document. Here are some of the values recognized:

Value	Type	Optional	Description
title	string	✅	Used as SEO title as well as string is left-hand side nav. When not used will default to the H1 tag in the document.
toc	boolean	✅	Determines whether pages should show the table of contents right-hand nav. When not included defaults to true.
timeToComplete	number	✅	Completion time for lab. Used in the conditional render of the sub-header under the H1 tag.
updated	date	✅	Date lab was last updated. Used in the conditional render of the sub-header under the H1 tag.
desc	string	✅	Short description of content within. Used for SEO.

Localization

Localization for the content is also supported through next-intl.

Tokens for localization are stored in the /translations folder as JSON files at the project root. If you'd like to localize specific content be sure to use the correct hooks depending the on the context you are rendering in (Client vs Server component).

However, since the bulk of the content is written in Markdown for it to be in different languages separate files are needed for each.

If you want to declare the language of a file append a locale code to the end of the file in the form of [filename].[locale-code].md. This means that content in various languages live next to each other in the file system so they can easily share certain paths.

The default language that a file is assumed to be in is English. Meaning that files named like so:

• content/test.en.md
• content/test.md

Are both understood to be in English and the path would then become /en/test at build.

Another thing to note is that relative links for the site are localized at runtime. They do not need to be localized per file.

For instance, a relative link to /foo/bar within a Markdown file would be localized based on the current locale the user is in at runtime. If in English the link would be prepended with the proper locale as /en/foo/bar.

Helpful Carbon links

• Carbon Design System monorepo
• Carbon components storybook
• Icon list