contentlayerdev / contentlayerdev/contentlayer

Simplify document type resolution

未关闭
#123 2 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
meta: never-stale needs-research pkg/source-files
主要语言
TypeScript
星标
3.5k
派生
192
PR 合并指标
30 天内没有已合并 PR

描述

## Context

In the `contentlayer/source-files` plugin there are currently **two mechanisms** to tell Contentlayer how map a given document (e.g. a `.md` file) to one of many document definitions (e.g. a `BlogPost`, `Page`, ...). The two mechanisms are:

1. Explicitly via the `filePathPattern` option provided for `defineDocumentType`
2. Implicitly by looking up a "type" field in a given document (configurable via `fieldOptions.typeFieldName`)

## Problem

I'm seeing two problems with the current design:

#### A: Technical problems/limitations

When using mechanism (1) there can be situations where the provided `filePathPattern` can overlap between document definitions and there currently is no way to explicitly configure the "precedence" document matching behaviour of Contentlayer.

#### B: Hard to understand / learn

Additionally to the technical problems (A) having two different ways to do the same thing (especially when they overlap) makes things much harder to understand - especially for new Contentlayer users who e.g. might ask themselves "which approach should I use?" or "which approach is _better_?".

I think that providing less ways to do the same thing is the right approach in most cases as it reduces cognitive overload.

Additionally there's also the complexity resulting of the possibility of combining both mechanisms (1) + (2).

## Solution

As an alternative to the current mechanisms (1) + (2) I'm proposing a single unified approach to let users specify how to map document files to document type definitions by simply implementing a `resolveDocumentType` function as a property in `makeSource` like the following:

#### As replacement for mechanism (1)

Assuming a content file structure like:

```
.
├── about.md
├── index.md
└── posts
├── post-1.md
├── post-2.md
└── post-3.md
```

```ts
const Post = defineDocumentType(() => ({
name: 'Post',
fields: {
// ...
}
}))

const Page = defineDocumentType(() => ({
name: 'Page',
fields: {
// ...
}
}))

export default makeSource({
contentDirPath: 'posts',
documentTypes: [Post, Page],
resolveDocumentType: (frontmatter, raw) => raw.sourceFilePath.startsWith('posts/') ? 'Post' : 'Page'
})
```

#### As replacement for mechanism (2)

Assuming each document as a frontmatter field called `type`

```ts
const Post = defineDocumentType(() => ({
name: 'Post',
fields: {
// ...
}
}))

const Page = defineDocumentType(() => ({
name: 'Page',
fields: {
// ...
}
}))

export default makeSource({
contentDirPath: 'posts',
documentTypes: [Post, Page],
resolveDocumentType: (frontmatter, raw) => frontmatter.type
})
```

## Feedback wanted

We'd love to hear your feedback on the proposed API change. 🙏

贡献指南

打开贡献指南

调研方向

从 contentlayer/source-files 插件开始,跟踪 makeSource、defineDocumentType、filePathPattern 和 fieldOptions.typeFieldName 当前如何解析文档类型。将这些路径与提议的 resolveDocumentType 示例进行比较。当 API 方向、优先级行为以及是否移除现有机制达成一致时,即视为完成。

由索引模型根据 Issue 内容生成。

评估

技术栈
typescript
领域
backend-api-design
Issue 类型
功能
难度
5/5
预计耗时
一周以上
活跃度
停滞
描述清晰度
基本清楚
新手友好度
25/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。