Reading Docusaurus code
Tags: opensource, beginners, javascript, docusaurus
Published: 2023-10-30 00:27:49

**Markdown Frontmatter**
One of the cool features in Docusaurus that I found is [Markdown Frontmatter](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#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.

```shell
---
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](https://github.com/facebook/docusaurus/blob/4e150d2b8247d44e964272e9a1a52a212d47ec01/packages/docusaurus-mdx-loader/src/frontMatter.ts) validates and processes frontmatter objects by using [Joi library](https://github.com/hapijs/joi) for the data validation.
```javascript
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](https://github.com/facebook/docusaurus/blob/4e150d2b8247d44e964272e9a1a52a212d47ec01/packages/docusaurus-mdx-loader/src/format.ts#L9) determines the desired format based on the given arguments. 
```javascript
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](https://github.com/facebook/docusaurus/blob/4e150d2b8247d44e964272e9a1a52a212d47ec01/packages/docusaurus-mdx-loader/src/processor.ts#L251). 
```javascript
...
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](https://github.com/features/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](https://github.com/facebook/docusaurus/blob/4e150d2b8247d44e964272e9a1a52a212d47ec01/packages/docusaurus-mdx-loader/package.json#L25). 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.