Reading Docusaurus code

Markdown Frontmatter
One of the cool features in Docusaurus that I found is Markdown Frontmatter. For those who do not know, which includes me, Frontmatter is commonly used to identify metadata in Markdown files. Frontmatter is one of the useful ways to enhance Markdown files by including metadata such as an ID, title, description, images, and more. This information is typically enclosed by lines --- on either side as below.

---
id: doc-markdown
title: Docs Markdown Features
description: Reading Docusaurus code
image: https://sample.com/mustard.png
---

# Markdown Features
My Document Markdown content

Code in Docusaurus
This module validates and processes frontmatter objects by using Joi library for the data validation.

import {
  JoiFrontMatter as Joi,
  validateFrontMatter,
} from '@docusaurus/utils-validation';

import type {FormatInput} from './index';

export type MDXFrontMatter = {
  format?: FormatInput;
};

export const DefaultMDXFrontMatter: MDXFrontMatter = {
  format: undefined,
};

// uses `Joi` to create a schema for validating objects, `MDXFrontMatter`. if validation fails -> uses DefaultMDXFrontMatter
const MDXFrontMatterSchema = Joi.object<MDXFrontMatter>({
  format: Joi.string().equal('md', 'mdx', 'detect').optional(),
}).default(DefaultMDXFrontMatter);

// validate frontMatter using MDXFrontMatterSchema -> return an object conforming to the MDXFrontMatter
export function validateMDXFrontMatter(frontMatter: unknown): MDXFrontMatter {
  return validateFrontMatter(frontMatter, MDXFrontMatterSchema, {
    allowUnknown: false,
  });
}

This module determines the desired format based on the given arguments.

import path from 'path';
import type { MDXFrontMatter } from './frontMatter';
import type { Format, FormatInput } from './index';

const mdFormatExtensions = [
  '.md',
  '.markdown',
  '.mdown',
  '.mkdn',
  '.mkd',
  '.mdwn',
  '.mkdown',
  '.ron',
];

// return file extension, `md` when extension of the filepath is one of the mdFormatExtensions options.
function getExtensionFormat(filepath: string): Format {
  const isMDFormat = mdFormatExtensions.includes(path.extname(filepath));
  // Bias toward mdx if unknown extension
  return isMDFormat ? 'md' : 'mdx';
}

// takes an object and returns type, `Format`
export function getFormat({
  filePath,
  frontMatterFormat,
  markdownConfigFormat,
}: {
  filePath: string;
  frontMatterFormat: MDXFrontMatter['format'];
  markdownConfigFormat: FormatInput;
}): Format {
  if (frontMatterFormat) {
    if (frontMatterFormat !== 'detect') {
      return frontMatterFormat;
    }
    return getExtensionFormat(filePath);
  }
  if (markdownConfigFormat !== 'detect') {
    return markdownConfigFormat;
  }
  return getExtensionFormat(filePath);
}

Finally, getFormat method is used in the following code.

...
export async function createProcessorCached({
  filePath,
  mdxFrontMatter,
  query,
  reqOptions,
}: {
  filePath: string;
  mdxFrontMatter: MDXFrontMatter;
  query: string | Options;
  reqOptions: Options;
}): Promise<SimpleProcessor> {
  const compilers = await createProcessorsCacheEntry({query, reqOptions});

  const format = getFormat({
    filePath,
    frontMatterFormat: mdxFrontMatter.format,
    markdownConfigFormat: reqOptions.markdownConfig.format,
  });

  return format === 'md' ? compilers.mdProcessor : compilers.mdxProcessor;
}

Strategies to locate the codes that I needed
Even after I chose my feature, it was hard for me to find the code related to the feature since it was a huge project. To be honest, I didn't know where to begin. That's when I started using GitHub Code Search. I began by typing the keyword frontmatter in my case. Several files came up. I noticed that they were using a library called @docusaurus/utils-validation. I navigated to the upper directory, docusaurus/packages/docusaurus-mdx-loader, and started examining the code.

Challenges

It was hard to start because I did not know where to begin.
Even GitHub Code Search did not help me much when I got over 50 files as a result in the beginning.
There are still many files that use frontmatter that I have not yet looked at because there are too many files.

Blog

Reading Docusaurus code

Avelyn Hyunjeong Choi

Join Our Newsletter. No Spam, Only the good stuff.

Related