You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
Explicitly via the filePathPattern option provided for defineDocumentType
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:
The idea is to have a clearer separation of the source from the transformation pipeline (defineDocuementType). resolveDocument would in this case be only specific only to md/mdx files.
The part that I still don't really like is that resolveDocument in defineDocumentType still takes a path. I think it's more natural for filePathPattern to exist in the makeSource section and maybe defineDocumentType can take a resolveType property?
This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.
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. aBlogPost
,Page
, ...). The two mechanisms are:filePathPattern
option provided fordefineDocumentType
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 inmakeSource
like the following:As replacement for mechanism (1)
Assuming a content file structure like:
As replacement for mechanism (2)
Assuming each document as a frontmatter field called
type
Feedback wanted
We'd love to hear your feedback on the proposed API change. 🙏
The text was updated successfully, but these errors were encountered: