feat: render links as relative paths

We previously rendered all page links as absolute paths e.g.
`/page.md`. This created some problems
- some page generators that use base path prefixes like `/docs/page.md`
  and thus need to rewrite these links, which is brittle
- text editors like VSCode cannot follow the markdown links properly
  because they think the links are absolute to the root `/` of the fs
- tools like textlint-rule-no-dead-link expect relative links to resolve
  them correctly

Now rendering them as relative paths.

As part of these changes it was also necessary to switch properties
parsing to render properties only as plaintext, not markdown. This is
fine because we consider frontmatter to be data (YML), not markup. Most
site generators cannot deal with markdown in frontmatter anyway.
This change was necessary because we need to parse page properties
before we can determine the destination path of the markdown file where
the page will be rendered to, and that would now require resolving
relative links.

Author: JohannesRudolph

README.md

@@ -77,7 +77,7 @@ The following [Notion API page property types](https://developers.notion.com/ref
 
 | Propety type     | Supported | Notes                         |
 | ---------------- | --------- | ----------------------------- |
-| Rich text        | ✅ Yes     | rendered as markdown string   |
+| Rich text        | ✅ Yes     | rendered as plaintext string  |
 | Number           | ✅ Yes     |                               |
 | Select           | ✅ Yes     | rendered as name              |
 | Multi Select     | ✅ Yes     | rendered as array of names    |

src/AssetWriter.ts

@@ -1,27 +1,25 @@
-import { promises as fs } from 'fs';
-import got from 'got';
-import { KeyvFile } from 'keyv-file';
-import * as mime from 'mime-types';
-
-import { RenderingLoggingContext } from './logger';
+import { promises as fs } from "fs";
+import got from "got";
+import { KeyvFile } from "keyv-file";
+import * as mime from "mime-types";
+import { RenderingContextLogger } from "./RenderingContextLogger";
 
 const cache = new KeyvFile({
   filename: ".cache/keyv.json",
 });
 
 export class AssetWriter {
-  constructor(readonly dir: string) {}
+  constructor(
+    private readonly dir: string,
+    private readonly logger: RenderingContextLogger
+  ) {}
 
   async store(name: string, buffer: Buffer) {
     await fs.mkdir(this.dir, { recursive: true });
     await fs.writeFile(`${this.dir}/${name}`, buffer);
   }
 
-  async download(
-    url: string,
-    fileName: string,
-    context: RenderingLoggingContext
-  ) {
+  async download(url: string, fileName: string) {
     // the got http lib promises to do proper user-agent compliant http caching
     // see https://github.com/sindresorhus/got/blob/main/documentation/cache.md
 
@@ -35,7 +33,7 @@ export class AssetWriter {
     const imageFile = fileName + "." + ext;
 
     const cacheInfo = response.isFromCache ? " (from cache)" : "";
-    context.info(`downloading ${imageFile}` + cacheInfo);
+    this.logger.info(`downloading ${imageFile}` + cacheInfo);
     await this.store(imageFile, response.rawBody);
 
     return imageFile;

src/BlockRenderer.ts

@@ -1,12 +1,19 @@
-import { RichText } from '@notionhq/client/build/src/api-types';
+import { RichText } from "@notionhq/client/build/src/api-types";
 
-import { AssetWriter } from './AssetWriter';
+import { AssetWriter } from "./AssetWriter";
 import {
-    Block, Emoji, ExternalFile, ExternalFileWithCaption, File, FileWithCaption, ImageBlock
-} from './Blocks';
-import { DeferredRenderer } from './DeferredRenderer';
-import { RenderingLoggingContext } from './logger';
-import { RichTextRenderer } from './RichTextRenderer';
+  Block,
+  Emoji,
+  ExternalFile,
+  ExternalFileWithCaption,
+  File,
+  FileWithCaption,
+  ImageBlock,
+} from "./Blocks";
+import { DeferredRenderer } from "./DeferredRenderer";
+import { RenderingContextLogger } from "./RenderingContextLogger";
+import { RichTextRenderer } from "./RichTextRenderer";
+import { RenderingContext } from "./RenderingContext";
 
 const debug = require("debug")("blocks");
 
@@ -22,8 +29,7 @@ export class BlockRenderer {
 
   async renderBlock(
     block: Block,
-    assets: AssetWriter,
-    context: RenderingLoggingContext
+    context: RenderingContext
   ): Promise<BlockRenderResult | null> {
     const renderMarkdown = async (text: RichText[]) => {
       return await this.richText.renderMarkdown(text, context);
@@ -63,7 +69,7 @@ export class BlockRenderer {
         };
       case "image":
         return {
-          lines: await this.renderImage(block, assets, context),
+          lines: await this.renderImage(block, context.assetWriter),
         };
       case "quote": {
         // it's legal for a notion block to be cmoposed of multiple lines
@@ -85,7 +91,7 @@ export class BlockRenderer {
       case "callout": {
         // render emoji as bold, this enables css to target it as `blockquote > strong:first-child`
         const content =
-          `**${this.renderIcon(block.callout.icon, context)}** ` +
+          `**${this.renderIcon(block.callout.icon, context.logger)}** ` +
           (await renderMarkdown(block.callout.text));
 
         return {
@@ -96,7 +102,7 @@ export class BlockRenderer {
         return { lines: "---" };
       case "child_database":
         const msg = `<!-- included database ${block.id} -->\n`;
-        const db = await this.deferredRenderer.renderChildDatabase(block.id);
+        const db = await this.deferredRenderer.renderChildDatabase(block.id, context.linkResolver);
         return { lines: msg + db.markdown };
       case "synced_block":
         // nothing to render, only the contents of the synced block are relevant
@@ -116,15 +122,15 @@ export class BlockRenderer {
           lines: this.renderUnsupported(
             `unsupported block type: ${block.type}`,
             block,
-            context
+            context.logger
           ),
         };
     }
   }
 
   private renderIcon(
     icon: File | ExternalFile | Emoji,
-    context: RenderingLoggingContext
+    logger: RenderingContextLogger
   ): string {
     switch (icon.type) {
       case "emoji":
@@ -134,19 +140,18 @@ export class BlockRenderer {
         return this.renderUnsupported(
           `unsupported icon type: ${icon.type}`,
           icon,
-          context
+          logger
         );
     }
   }
 
   async renderImage(
     block: ImageBlock,
-    assets: AssetWriter,
-    context: RenderingLoggingContext
+    assets: AssetWriter
   ): Promise<string> {
     const url = this.parseUrl(block.image);
 
-    const imageFile = await assets.download(url, block.id, context);
+    const imageFile = await assets.download(url, block.id);
 
     // todo: caption support
     const markdown = `![image-${block.id}](./${imageFile})`;
@@ -172,7 +177,7 @@ export class BlockRenderer {
   private renderUnsupported(
     msg: string,
     obj: any,
-    context: RenderingLoggingContext
+    context: RenderingContextLogger
   ): string {
     context.warn(msg);
     debug(msg + "\n%O", obj);

src/ChildDatabaseRenderer.ts

@@ -1,13 +1,18 @@
-import { Page } from '@notionhq/client/build/src/api-types';
-
-import { SyncConfig } from './';
-import { lookupDatabaseConfig } from './config';
-import { Database } from './Database';
-import { DatabaseViewRenderer } from './DatabaseViewRenderer';
-import { DeferredRenderer } from './DeferredRenderer';
-import { NotionApiFacade } from './NotionApiFacade';
-import { RenderDatabasePageTask } from './RenderDatabasePageTask';
-import { DatabaseConfig, DatabaseConfigRenderPages, DatabaseConfigRenderTable } from './SyncConfig';
+import { Page } from "@notionhq/client/build/src/api-types";
+
+import { SyncConfig } from "./";
+import { lookupDatabaseConfig } from "./config";
+import { Database } from "./Database";
+import { DatabaseViewRenderer } from "./DatabaseViewRenderer";
+import { DeferredRenderer } from "./DeferredRenderer";
+import { NotionApiFacade } from "./NotionApiFacade";
+import { PageLinkResolver } from "./PageLinkResolver";
+import { RenderDatabasePageTask } from "./RenderDatabasePageTask";
+import {
+  DatabaseConfig,
+  DatabaseConfigRenderPages,
+  DatabaseConfigRenderTable,
+} from "./SyncConfig";
 
 const debug = require("debug")("child-database");
 
@@ -17,22 +22,31 @@ export class ChildDatabaseRenderer {
     private readonly publicApi: NotionApiFacade,
     private readonly deferredRenderer: DeferredRenderer,
     private readonly viewRenderer: DatabaseViewRenderer
-  ) { }
+  ) {}
 
-  async renderChildDatabase(databaseId: string): Promise<Database> {
+  async renderChildDatabase(
+    databaseId: string,
+    linkResolver: PageLinkResolver
+  ): Promise<Database> {
     const dbConfig = lookupDatabaseConfig(this.config, databaseId);
 
     // no view was defined for this database, render as a plain inline table
     const allPages = await this.fetchPages(databaseId, dbConfig);
 
-    const renderPages = dbConfig.renderAs === "pages+views"
+    const renderPages = dbConfig.renderAs === "pages+views";
 
-    debug("rendering child database " + databaseId + " as " + dbConfig.renderAs);
+    debug(
+      "rendering child database " + databaseId + " as " + dbConfig.renderAs
+    );
 
     if (renderPages) {
       const pageConfig = dbConfig as DatabaseConfigRenderPages;
       const entries = await this.queuePageRendering(allPages, pageConfig);
-      const markdown = await this.viewRenderer.renderViews(entries, dbConfig as DatabaseConfigRenderPages);
+      const markdown = await this.viewRenderer.renderViews(
+        entries,
+        dbConfig as DatabaseConfigRenderPages,
+        linkResolver
+      );
 
       return {
         config: dbConfig,
@@ -42,15 +56,18 @@ export class ChildDatabaseRenderer {
     } else {
       // render table
       const entries = await this.queueEntryRendering(allPages, dbConfig);
-      const markdown = this.viewRenderer.renderViews(entries, dbConfig);
-  
+      const markdown = this.viewRenderer.renderViews(
+        entries,
+        dbConfig,
+        linkResolver
+      );
+
       return {
         config: dbConfig,
         entries,
         markdown,
       };
     }
-
   }
 
   private async queueEntryRendering(

src/DatabasePageRenderer.ts

@@ -2,14 +2,13 @@ import * as fsc from "fs";
 
 import { Page } from "@notionhq/client/build/src/api-types";
 
-import { AssetWriter } from "./AssetWriter";
 import { FrontmatterRenderer } from "./FrontmatterRenderer";
-import { RenderingLoggingContext } from "./logger";
 import { PropertiesParser } from "./PropertiesParser";
 import { RecursiveBodyRenderer } from "./RecursiveBodyRenderer";
 import { RenderDatabasePageTask as RenderDatabasePageTask } from "./RenderDatabasePageTask";
 import { DatabaseConfigRenderPages } from "./SyncConfig";
 import { slugify } from "./slugify";
+import { RenderingContext } from "./RenderingContext";
 
 const fs = fsc.promises;
 
@@ -41,35 +40,33 @@ export class DatabasePageRenderer {
       frontmatter: frontmatterProperties,
       properties: props,
       render: async () => {
-        const context = new RenderingLoggingContext(page.url, file);
-
+        
+        const context = new RenderingContext(page.url, file)
+        
         if (page.archived) {
           // have to skip rendering archived pages as attempting to retrieve the block will result in a HTTP 404
-          context.warn(`page is archived - skipping`);
+          context.logger.warn(`page is archived - skipping`);
 
           return;
         }
 
         try {
-          const assetWriter = new AssetWriter(destDir);
-
           const frontmatter = this.frontmatterRenderer.renderFrontmatter(frontmatterProperties);
           const body = await this.bodyRenderer.renderBody(
             page,
-            assetWriter,
             context
           );
 
           await fs.mkdir(destDir, { recursive: true });
           await fs.writeFile(file, frontmatter + body);
 
-          context.complete();
+          context.logger.complete();
         } catch (error) {
           // While catch-log-throw is usually an antipattern, it is the renderes job to orchestrate the rendering
           // job with concerns like logging and  writing to the outside world. Hence this place is appropriate.
           // We need to throw the error here so that the rendering process can crash with a proper error message, since
           // an error at this point here is unrecoverable.
-          context.error(error);
+          context.logger.error(error);
           throw error;
         }
       },

src/DatabaseViewRenderer.ts

@@ -1,6 +1,7 @@
 import { DatabaseConfigRenderTable } from ".";
 import { LinkRenderer } from "./LinkRenderer";
 import * as markdownTable from "./markdown-table";
+import { PageLinkResolver } from "./PageLinkResolver";
 import { RenderDatabaseEntryTask } from "./RenderDatabaseEntryTask";
 import { RenderDatabasePageTask } from "./RenderDatabasePageTask";
 import { DatabaseConfigRenderPages, DatabaseView } from "./SyncConfig";
@@ -11,15 +12,16 @@ export class DatabaseViewRenderer {
 
   public renderViews(
     entries: (RenderDatabasePageTask | RenderDatabaseEntryTask)[],
-    config: DatabaseConfigRenderPages | DatabaseConfigRenderTable
+    config: DatabaseConfigRenderPages | DatabaseConfigRenderTable,
+    linkResolver: PageLinkResolver
   ): string {
     const configuredViews = config.views || [{}];
 
     const views = configuredViews?.map((view) => {
       const groupByProperty = view?.properties?.groupBy;
 
       if (!groupByProperty) {
-        return this.renderView(entries, null, view);
+        return this.renderView(entries, null, view, linkResolver);
       } else {
         const grouped = new Array(
           ...groupBy(entries, (p) =>
@@ -28,7 +30,7 @@ export class DatabaseViewRenderer {
         );
 
         return grouped
-          .map(([key, pages]) => this.renderView(pages, key, view))
+          .map(([key, pages]) => this.renderView(pages, key, view, linkResolver))
           .join("\n\n");
       }
     });
@@ -39,7 +41,8 @@ export class DatabaseViewRenderer {
   private renderView(
     pages: (RenderDatabasePageTask | RenderDatabaseEntryTask)[],
     titleAppendix: string | null,
-    view: DatabaseView
+    view: DatabaseView,
+    linkResolver: PageLinkResolver
   ): string {
     if (!pages[0]) {
       return "<!-- no pages inside this database -->";
@@ -60,15 +63,17 @@ export class DatabaseViewRenderer {
         cols.map((c, i) => {
           const content = escapeTableCell(r.properties.properties.get(c));
           return i == 0 && isRenderPageTask(r)
-            ? this.linkRenderer.renderPageLink(content, r) // make the first cell a relative link to the page
+            ? this.linkRenderer.renderPageLink(content, r, linkResolver) // make the first cell a relative link to the page
             : content;
         })
       )
     );
 
     const tableMd = markdownTable.markdownTable(table);
     if (view.title) {
-      const formattedTitle = [view.title, titleAppendix].filter(x => !!x).join(" - ");
+      const formattedTitle = [view.title, titleAppendix]
+        .filter((x) => !!x)
+        .join(" - ");
       return `## ${formattedTitle}\n\n` + tableMd;
     } else {
       return tableMd;