feat: add options to explicitly control Database page categories

Author: JohannesRudolph

src/DatabasePageRenderer.ts

@@ -11,8 +11,9 @@ export class DatabasePageRenderer {
   ) {}
 
   async renderDatabase(databaseId: string): Promise<Database> {
-    const dbConfig = this.config[databaseId] || {
-      parentCategory: "",
+    const dbConfig: DatabaseConfig = this.config[databaseId] || {
+      outSubDir: "",
+      pageCategoryValuePrefix: "",
       properties: {
         category: "category",
       },

src/PageRenderer.ts

@@ -11,6 +11,8 @@ import { DatabaseConfig } from "./SyncConfig";
 import { PropertiesParser } from "./PropertiesParser";
 import { logger } from "./logger";
 
+const debug = require("debug")("page");
+
 const fs = fsc.promises;
 
 export class PageRenderer {
@@ -25,12 +27,19 @@ export class PageRenderer {
     const props = this.propertiesParser.filter(config, parsed);
 
     const name = props.values["name"];
+    if (!name) {
+      this.throwMissingRequiredProperty("name", page);
+    }
+
+    const category = props.values[props.keys.get(config.properties.category)!!];
+    if (category) {
+      this.throwMissingRequiredProperty(config.properties.category, page);
+    }
+
     const nameSlug = slugify(name);
-    const categorySlug =
-      config.parentCategory + slugify(props.values["category"]);
+    const categorySlug = config.pageCategoryValuePrefix + slugify(category);
 
-    const dir = `docs/${categorySlug}`;
-    const file = `${dir}/${nameSlug}.md`;
+    const file = `${config.outDir}/${nameSlug}.md`;
 
     // Design: all the rendering performance could be greatly enhanced writing directly to output streams instead
     // of concatenating all in memory. OTOH naively concatenatic strings is straightforward, easier to debug and rendering
@@ -42,7 +51,7 @@ export class PageRenderer {
       file,
       properties: props,
       render: async () => {
-        const assetWriter = new AssetWriter(dir);
+        const assetWriter = new AssetWriter(config.outDir);
 
         const frontmatter = this.frontmatterRenderer.renderFrontmatter(
           props.values
@@ -53,11 +62,18 @@ export class PageRenderer {
           assetWriter
         );
 
-        await fs.mkdir(dir, { recursive: true });
+        await fs.mkdir(config.outDir, { recursive: true });
         await fs.writeFile(file, frontmatter + body);
 
         logger.info("wrote: " + file);
       },
     };
   }
+
+  private throwMissingRequiredProperty(propertyName: string, page: Page) {
+    const msg = `Page ${page.url} is missing required property ${propertyName}`;
+    debug(msg + "\n%O", page);
+
+    throw new Error(msg);
+  }
 }

src/SyncConfig.ts

@@ -8,7 +8,9 @@ export interface SyncConfig {
   cmsDatabaseId: string;
 
   /**
-   * The output directory where the sync will place pages, e.g. "docs/"
+   * The output directory where the sync will place pages.
+   * 
+   * Example: "docs/"
    */
   outDir: string;
 
@@ -27,15 +29,41 @@ export interface SyncConfig {
 
 export interface DatabaseConfig {
   /**
-   * Name of the parent category to use 
+   * The output directory where the sync will place pages of this database.
+   * 
+   * Example: "docs/mydb/"
    */
-  parentCategory: string;
+  outDir: string;
+
+  /**
+   * The prefix to apply to the category value of all pages.
+   * This is useful to create a unique category name for all pages of this database.
+   * 
+   * Example: "mydb/"
+   */
+  pageCategoryValuePrefix: string;
+
   /**
    * Notion API https://developers.notion.com/reference/post-database-query#post-database-query-sort
    */
   sorts?: Sort[];
+
+  /**
+   * Configuration options for Notion API page properties
+   */
   properties: {
+    /**
+     * The Notion API page property that provides the value to use for the markdown page category.
+     * This will be prefixed by DatabaseConfig.pageCategoryValuePrefix
+     * 
+     * Example: "Cluster"
+     */
     category: string;
+    
+    /**
+     * A whitelist of Notion API page property names to include in the markdown page properties.
+     * Use this to select properties for export and control their ordering in rendered tables.
+     */
     include?: string[];
   };
 }