doc(notion): create documentation

Author: kerwanp

docs/integration_granular_permissions.gif

@@ -2,22 +2,15 @@ import type * as core from '@contentlayer/core'
 import { processArgs } from '@contentlayer/core'
 import { pipe, S, T } from '@contentlayer/utils/effect'
 import { NotionRenderer } from '@notion-render/client';
-import type * as notion from '@notionhq/client';
 
 import { fetchAllDocuments } from './fetchData/index.js'
 import { provideSchema } from './schema/provideSchema.js'
-import type * as LocalSchema from './schema/types.js'
 import type { PluginOptions } from "./types.js"
 
 export * from './schema/types.js'
 
-export type Args = {
-    client: notion.Client,
-    renderer?: NotionRenderer,
-    databaseTypes: LocalSchema.DatabaseTypes
-}
 
-export const makeSource: core.MakeSourcePlugin<Args & PluginOptions> = async (args) => {
+export const makeSource: core.MakeSourcePlugin<PluginOptions & core.PartialArgs> = async (args) => {
     const {
         options,
         extensions,

docs/table.png

@@ -1,8 +1,8 @@
 import type * as core from '@contentlayer/core'
-import type { FieldDef } from '@contentlayer/core';
 import type { OT } from "@contentlayer/utils/effect";
 import { pipe, T } from "@contentlayer/utils/effect";
 
+import type { FieldDef } from '../types.js';
 import { provideDatabaseFieldSchema } from './provideDatabaseFieldSchema.js';
 import type { ProvideSchemaArgs } from "./provideSchema.js";
 import type { DatabaseTypeDef } from "./types.js";

packages/@contentlayer/source-notion/src/index.ts

@@ -2,11 +2,6 @@ import type { Thunk } from "@contentlayer/utils"
 import type { QueryDatabaseParameters } from "@notionhq/client/build/src/api-endpoints"
 
 export type DatabaseFieldTypeDefBase = {
-    /**
-     * When required, pages without this property defined will not be generated.
-     */
-    isRequired?: boolean,
-
     /**
      * Map this property to a specific key.
      * Defaults to the property name.
@@ -17,25 +12,49 @@ export type DatabaseFieldTypeDefBase = {
      * Field description used to generate comments.
      */
     description?: string;
-} & ({ id: string } | { label: string })
+
+    /**
+     * When required, pages without this property defined will not be generated.
+     */
+    isRequired?: boolean,
+} & ({ id: string } | { name: string })
 
 export type DatabaseRelationFieldTypeDef = DatabaseFieldTypeDefBase & {
+    /**
+     * Type of the property to configure it.
+     */
     type: 'relation',
-    // TODO : Not used yet
-    relation: DatabaseType,
-    single?: boolean,
-}
 
-export type DatabaseRollupFieldTypeDef = DatabaseFieldTypeDefBase & {
-    type: 'rollup',
-    relation: DatabaseType,
+    /**
+     * Database related to this relation.
+     * 
+     * TODO : Will be used for Rollup properties.
+     */
+    relation?: DatabaseType,
+
+    /**
+     * If true, the property will be of type `string` instead of type `string[]`
+     * and only the first item will be taken.
+     */
+    single?: boolean,
 }
 
-export type DatabaseFieldTypeDef = DatabaseFieldTypeDefBase | DatabaseRollupFieldTypeDef | DatabaseRelationFieldTypeDef
+export type DatabaseFieldTypeDef = DatabaseFieldTypeDefBase | DatabaseRelationFieldTypeDef
 
 export type DatabaseTypeDef<Flattened extends boolean = true, DefName extends string = string> = {
+    /**
+     * The database name.
+     */
     name: DefName,
+
+    /**
+     * The database description used to generate comments.
+     */
     description?: string,
+
+    /**
+     * The database ID used as the content source.
+     */
     databaseId: string,
 
     /**
@@ -56,6 +75,10 @@ export type DatabaseTypeDef<Flattened extends boolean = true, DefName extends st
      */
     query?: Omit<QueryDatabaseParameters, 'database_id' | 'filter_properties' | 'start_cursor' | 'page_size'>
 
+    /**
+     * The fields configuration, usefull to remap keys and configure complex properties.
+     * Not required as the properties types are already inferred.
+     */
     fields?: Flattened extends false ? Record<string, DatabaseFieldTypeDef> | DatabaseFieldTypeDef[] : DatabaseFieldTypeDef[]
 }
 

packages/@contentlayer/source-notion/src/schema/provideDatabaseSchema.ts

@@ -10,7 +10,7 @@ export const findDatabaseFieldDef = ({ databaseTypeDef, property }: FindDatabase
     if (!databaseTypeDef.fields) return;
 
     return databaseTypeDef.fields.find((fieldDef) => {
-        if ('label' in fieldDef) return fieldDef.label === property.name
+        if ('label' in fieldDef) return fieldDef.name === property.name
         if ('id' in fieldDef) return fieldDef.id === property.id
     })
 }

packages/@contentlayer/source-notion/src/schema/types.ts

@@ -1,21 +1,14 @@
 import type * as core from '@contentlayer/core';
+import type { NotionRenderer } from '@notion-render/client';
+import type * as notion from '@notionhq/client'
 import type { DatabaseObjectResponse, PageObjectResponse } from "@notionhq/client/build/src/api-endpoints"
 
-export type PluginOptions = {
-    fieldOptions?: FieldOptions
-}
+import type { DatabaseTypes } from './schema/types.js';
 
-export type FieldOptions = {
-    /**
-     * Name of the field containing the body/content extracted when `contentType` is `markdown` or `mdx`.
-     * @default "body"
-     */
-    bodyFieldName?: string
-    /**
-     * Name of the field containing the name of the document type (or nested document type).
-     * @default "type"
-     */
-    typeFieldName?: string
+export type PluginOptions = {
+    client: notion.Client,
+    renderer?: NotionRenderer,
+    databaseTypes: DatabaseTypes
 }
 
 export type FieldDef = core.FieldDef & { propertyKey: string }