Notion To MD – Blog

Mastering Media Handling in notion-to-md v4 - Download, Upload, and Direct Strategies

Wed, 23 Apr 2025 00:00:00 +0000

Notion is a fantastic tool for content creation, but when you want to programmatically convert your Notion pages into Markdown, HTML, or other formats using notion-to-md, you hit a common challenge: handling media assets. Images, files, PDFs, and videos stored in Notion use temporary URLs that expire, making them unsuitable for permanent content like websites or documentation.

Luckily, notion-to-md v4 provides a robust Media Handling system with multiple strategies to solve this exact problem. This guide walks you through each strategy, explaining what it does, when to use it, and how to implement it with practical examples.

Prerequisites

This guide assumes you have a basic Node.js project set up with notion-to-md installed. Here’s how to get started:

// First, install the required packages
// npm install @notionhq/client notion-to-md
// or: yarn add @notionhq/client notion-to-md

// Basic setup for NotionConverter
import { Client } from '@notionhq/client';
import { NotionConverter } from 'notion-to-md';
import * as path from 'path';
import * as fs from 'fs';

// Initialize the Notion client with your integration token
const notion = new Client({
 auth: process.env.NOTION_TOKEN,
});

// Create a basic NotionConverter instance
const baseConverter = new NotionConverter(notion);

// The page ID you want to convert
const pageId = 'your-notion-page-id'; // Replace with your actual page ID

Understanding Media Handling Strategies

notion-to-md offers three primary strategies to manage media assets:

Direct Strategy: Uses the original Notion URLs (default behavior). Optionally buffers content for in-memory processing.
Download Strategy: Downloads media files to your local filesystem.
Upload Strategy: Uploads media files to an external service (like S3, Cloudinary, etc.).

Each strategy is designed for different use cases. Let’s explore them in detail.

Strategy 1: Direct Strategy (The Default)

The Direct Strategy is the default approach in notion-to-md if you don’t configure any other media handler.

What it does

It preserves the original URLs provided by Notion for all media files in your output markdown.

When to use

For quick development and testing where temporary URLs are acceptable
When you need to preprocess media files before they appear in your output
In applications where another system will handle the media files separately

Basic Usage (No Configuration Needed)

import { Client } from '@notionhq/client';
import { NotionConverter } from 'notion-to-md';

// Create a Notion client
const notion = new Client({ auth: process.env.NOTION_TOKEN });

// Create a converter with default (Direct) strategy
const converter = new NotionConverter(notion);

// Convert a page - media URLs will remain unchanged
converter.convert(pageId).then(({ content }) => {
 console.log(content);
 // Markdown output example:
 // ![Image](https://prod-files-secure.s3.us-west-2.amazonaws.com/...)
});

Advanced: In-Memory Buffering

A powerful feature of the Direct Strategy is its ability to buffer media content directly in memory.

What it does

It fetches media files from Notion and attaches them as Node.js Buffer objects to the block data structure during conversion. This lets you:

Process media directly (resize images, extract text from PDFs, etc.)
Embed media directly in output (e.g., as Base64 encoded data)
Implement custom handling without saving files to disk

Configuration

To enable buffering, use the useDirectStrategy method with a configuration object:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


import { Client } from '@notionhq/client';
import { NotionConverter } from 'notion-to-md';

// Create basic clients
const notion = new Client({ auth: process.env.NOTION_TOKEN });

// Configure converter with Direct Strategy + buffering
const converter = new NotionConverter(notion).useDirectStrategy({
 // Simple configuration - buffer all media types
 buffer: true,

 // OR use detailed configuration:
 /*
 buffer: {
 // Which references to buffer: blocks and/or properties
 enableFor: ['block', 'database_property'],

 // Which block types to buffer (when enableFor includes 'block')
 includeBlockContentTypes: ['image', 'pdf', 'video'],

 // Maximum buffer size (5MB limit in this example)
 maxBufferSize: 5 * 1024 * 1024,
 }
 */
});

Note

Refer to Direct stategy API Reference to know more about the buffer configuration

and here is how you access the buffer:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


import { Client } from '@notionhq/client';
import { NotionConverter } from 'notion-to-md';
import { MDXRenderer } from "notion-to-md/plugins/renderer";

const notion = new Client({ auth: process.env.NOTION_TOKEN });

const renderer = new MDXRenderer();

renderer.createBlockTransformer('image', {
 transform: async ({ block, utils }) => {
 // Access the buffer directly from the block
 if (block.buffer) {
 // We have the image data as a Buffer!
 const base64Image = block.buffer.toString('base64');
 return `<img src="data:image/png;base64,${base64Image}" alt="Embedded image" />`;
 } else {
 // Fallback to URL if buffer is unavailable (in case of errors and stuff)
 const imageUrl =
 block.image.type === 'external'
 ? block.image.external.url
 : block.image.file.url;
 return `![Image](${imageUrl})`;
 }
 },
});

const converter = new NotionConverter(notion).useDirectStrategy({
 buffer: true,
 ...
}).withRenderer(renderer);

// Convert a page with buffered media
converter.convert(pageId);

With buffering, each media block (like image, PDF, video) can have a buffer property containing the raw file data. This enables powerful custom processing directly in your transformers.

Note

Strategy 2: Download Strategy

The Download Strategy saves media files from Notion to your local filesystem.

What it does

Fetches media files from Notion and saves them to a specified directory
Updates URLs in the output to point to the locally saved files
Optionally tracks which files have been downloaded to avoid duplicates

When to use

For static websites where media is served alongside content. Great for all types of static site generators (example: Hugo, jekyll, etc)
For offline documentation or content that needs to work without internet
When you need permanent local copies of Notion media files

Configuration

Use the downloadMediaTo method with appropriate settings:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


import { Client } from '@notionhq/client';
import { NotionConverter } from 'notion-to-md';
import * as path from 'path';

const notion = new Client({ auth: process.env.NOTION_TOKEN });

const converter = new NotionConverter(notion).downloadMediaTo({
 // Required: Where to save the files
 outputDir: path.resolve('./public/assets/media'),

 // Optional: Convert filesystem paths to URLs for markdown
 transformPath: (localPath) => {
 // your logic to transform local path to web accessible path
 },

 // Optional: Control for which Notion entity the media is downloaded
 enableFor: ['block', 'database_property'],

 // Optional: Skip URLs that are already from external sources
 preserveExternalUrls: true,
});

converter.convert(pageId);

The optional transformPath function converts the local path where a media file is saved into the URL used in your final Markdown. This ensures your media links work correctly in the final output (e.g., on a website).

Example:

Local Path: /path/to/project/public/assets/media/image.png
transformPath Output: /assets/media/image.png (This becomes the URL like ![alt](/assets/media/image.png) in your Markdown)

Make sure this output URL matches how your web server or static site generator serves the files. If you omit transformPath, the library defaults to using the local file path as the reference, which might not be web-accessible or work as intended on a website.

Note

Refer to Download stategy API Reference to know more about the individual configuration options

Example: Complete Workflow for Static Site

Here’s a more complete example showing a typical workflow for a static site:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


import { Client } from '@notionhq/client';
import { NotionConverter } from 'notion-to-md';
import { DefaultExporter } from 'notion-to-md/plugins/exporter';
import * as path from 'path';

async function exportNotionPageToStaticSite() {
 // Setup
 const notion = new Client({ auth: process.env.NOTION_TOKEN });
 const pageId = 'your-page-id';
 const outputDir = path.resolve('./content');
 const mediaDir = path.resolve('./public/images/notion');

 // Configure exporter to save markdown file
 const exporter = new DefaultExporter({
 outputType: 'file',
 outputPath: path.join(outputDir, `${pageId}.md`),
 });

 // Configure converter with Download Strategy and Exporter
 const converter = new NotionConverter(notion)
 .withExporter(exporter)
 .downloadMediaTo({
 outputDir: mediaDir,
 transformPath: (localPath) =>
 `/images/notion/${path.basename(localPath)}`,
 });

 // Convert the page
 await converter.convert(pageId);

 console.log(`✓ Exported page to ${outputDir}`);
 console.log(`✓ Downloaded media to ${mediaDir}`);
}

exportNotionPageToStaticSite().catch(console.error);

The DefaultExporter handles file creation and directory management for you. You don’t need to manually create directories or write files - just specify the output path and directory.

Note

For more information about exporters and their configuration options, check out the Exporter Plugin documentation.

Strategy 3: Upload Strategy

The Upload Strategy sends media files from Notion to an external storage service.

What it does

Fetches media files from Notion
Uses your custom uploadHandler function to upload them to a service (AWS S3, Cloudinary, etc.)
Updates URLs in the output markdown to point to the newly uploaded files
Optionally tracks which files have been uploaded to avoid duplicates
Optionally cleans up files that are no longer referenced

When to use

For web applications where media needs to be on a CDN
When integrating with cloud storage services
For scalable solutions that need reliable, permanent URLs

Configuration

Use the uploadMediaUsing method with your custom upload handler:

import { Client } from '@notionhq/client';
import { NotionConverter } from 'notion-to-md';
// You would typically import your cloud storage SDK here
// import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
// import { Upload } from '@aws-sdk/lib-storage';

// Create basic clients
const notion = new Client({ auth: process.env.NOTION_TOKEN });

// Configure converter with Upload Strategy
const converter = new NotionConverter(notion).uploadMediaUsing({
 // Required: Your custom upload handler function
 uploadHandler: async (originalUrl, contextId, blockType) => {
 console.log(
 `Uploading media from ${originalUrl} (Block type: ${blockType})`,
 );

 // This is where you would implement your actual upload logic
 // Example (pseudo-code):
 /*
 // Download the file from Notion first
 const response = await fetch(originalUrl);
 const fileBuffer = await response.arrayBuffer();

 // Upload to your chosen service (S3, Cloudinary, etc.)
 const fileName = `notion-${contextId}.png`;
 const uploadedUrl = await uploadToMyService(fileBuffer, fileName);
 */

 // For demo purposes, just return a fake URL
 return `https://my-cdn.example.com/media/${contextId}.png`;
 },

 // Optional: Transform the URL after upload
 transformPath: (uploadedUrl) => {
 // Add cache-busting or other modifications
 return `${uploadedUrl}?v=${Date.now()}`;
 },

 // Optional: Clean up files that are no longer referenced
 cleanupHandler: async (manifestEntry) => {
 console.log(`Cleaning up: ${manifestEntry.mediaInfo.uploadedUrl}`);
 // Your deletion logic here
 },

 // Optional: Settings to control behavior
 enableFor: ['block', 'database_property'],
 preserveExternalUrls: true,
 failForward: true,
});

// Convert a page - media will be uploaded and links updated
converter.convert(pageId).then(({ content }) => {
 console.log(content);
 // Markdown output example:
 // ![Image](https://my-cdn.example.com/media/block123.png?v=1650000000000)
});

Real-World Example: S3 Upload

Here’s a more concrete example using AWS S3:

import { Client } from '@notionhq/client';
import { NotionConverter } from 'notion-to-md';
import {
 S3Client,
 PutObjectCommand,
 DeleteObjectCommand,
} from '@aws-sdk/client-s3';
import fetch from 'node-fetch';

async function convertWithS3Upload() {
 // Basic setup
 const notion = new Client({ auth: process.env.NOTION_TOKEN });
 const pageId = 'your-page-id';

 // S3 configuration
 const s3Client = new S3Client({
 region: 'us-east-1',
 credentials: {
 accessKeyId: process.env.AWS_ACCESS_KEY_ID,
 secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
 },
 });
 const bucketName = 'my-notion-media-bucket';

 // Configure converter with Upload Strategy
 const converter = new NotionConverter(notion).uploadMediaUsing({
 uploadHandler: async (originalUrl, contextId, blockType) => {
 try {
 // 1. Download the file from Notion
 const response = await fetch(originalUrl);
 if (!response.ok) {
 throw new Error(`Failed to fetch from Notion: ${response.status}`);
 }
 const buffer = await response.arrayBuffer();

 // 2. Determine file extension (simplified)
 const contentType =
 response.headers.get('content-type') || 'application/octet-stream';
 const extension = contentType.split('/')[1] || 'bin';

 // 3. Create a unique filename
 const filename = `notion-media/${contextId}.${extension}`;

 // 4. Upload to S3
 const command = new PutObjectCommand({
 Bucket: bucketName,
 Key: filename,
 Body: Buffer.from(buffer),
 ContentType: contentType,
 // Make the object publicly readable
 ACL: 'public-read',
 });

 await s3Client.send(command);

 // 5. Return the public URL
 return `https://${bucketName}.s3.amazonaws.com/${filename}`;
 } catch (error) {
 console.error('Upload failed:', error);
 throw error;
 }
 },
 // Clean up handler to delete files when they're removed from Notion
 cleanupHandler: async (manifestEntry) => {
 // Extract the key from the URL
 const url = new URL(manifestEntry.mediaInfo.uploadedUrl);
 const key = url.pathname.substring(1); // Remove leading slash

 // Delete the file from S3
 try {
 await s3Client.send(
 new DeleteObjectCommand({
 Bucket: bucketName,
 Key: key,
 }),
 );
 console.log(`Deleted ${key} from S3`);
 } catch (error) {
 console.error(`Failed to delete ${key}:`, error);
 }
 },
 });

 // Convert the page
 const { content } = await converter.convert(pageId);
 console.log('Conversion complete with S3 upload');
 return content; // or use exporter
}

convertWithS3Upload().then(console.log).catch(console.error);

⚠️

Security Note: The S3 example assumes your bucket is configured to allow public access to uploaded files. In production, you might want a more sophisticated setup with proper access controls.

Choosing the Right Strategy

Strategy	Use Case	Pros	Cons
Direct	Development, testing, in-memory processing	Default, simple, enables buffering	URLs expire, not for permanent content
Download	Static sites, local hosting, offline documentation	Easy setup, permanent local files	Requires disk space, path management needed
Upload	Web apps, CDNs, cloud storage integration	Scalable, reliable URLs, CDN benefits	Requires custom upload code, potentially complex setup

Strategy Selection Guide

Choose Direct Strategy with buffering if:
- You need to manipulate media files in memory
- You want to embed media directly (e.g., as Base64)
- You’re doing development/testing
Choose Download Strategy if:
- You’re building a static site with local media
- You need offline content access
- You want a simple setup with local files
Choose Upload Strategy if:
- You’re developing a web app with cloud storage
- You need CDN performance benefits
- You want permanent, scalable media hosting

Conclusion

notion-to-md v4’s media handling strategies provide flexible, powerful solutions to the common problem of dealing with Notion’s temporary media URLs. By choosing the right strategy for your use case, you can ensure your converted content includes permanent, correctly linked media assets.

Direct Strategy with buffering gives you access to media data in memory
Download Strategy creates local files for static sites and offline use
Upload Strategy integrates with cloud storage for scalable web applications

Remember to configure your chosen strategy properly, especially focusing on the path transformation functions that ensure your media references work correctly in the final output.

Happy converting!

How to Convert Notion Properties to Frontmatter with notion-to-md v4

Wed, 12 Mar 2025 00:00:00 +0000

Converting Notion page properties to frontmatter is a common need when using Notion as a CMS. notion-to-md v4 makes this straightforward with its built-in support and further we can see how we can customize it. Let’s explore how!

Built-In Frontmatter Support

The default MDX renderer that comes with notion-to-md v4 already supports frontmatter generation. By default it is set to false. Here’s how you utilize it:

import { NotionConverter } from 'notion-to-md';
import { MDXRenderer } from 'notion-to-md/plugins/renderer';

const notionClient = new NotionClient({ auth: process.env.NOTION_TOKEN });

const n2m = new NotionConverter(notionClient).withRenderer(
 new MDXRenderer({
 frontmatter: true, // Enable frontmatter generation, default is false
 }),
);

await n2m.convert('your-page-id');

This will automatically convert all Notion page properties to YAML frontmatter! Here is our sample page with certain properties:

and this is what the output looks like:

---
Created: '2025-01-04T02:17:00.000Z'
Tags: ['V4', 'notion to md', 'test']
PublishURL: '/page-1'
Name: 'Notion Properties as Frontmatter'
---

Customizing Frontmatter

While the default method works well in many situations, you may require additional control over which attributes are included and how they are displayed. The MDXRenderer offers several configuration options for customizing frontmatter.

Basic Configuration

const renderer = new MDXRenderer({
 frontmatter: {
 // Only include specific properties
 // include: ["PublishUrl"],
 // or
 exclude: ['PublishURL'],

 // set defaults
 defaults: {
 draft: true,
 comments: 'true',
 },

 rename: {
 Name: 'title',
 },
 },
});

Tip

To know more about the Default renderer configuration options, read the MDXRenderer configuration

Running this against the same Notion page will produce the following frontmatter:

---
Created: '2025-01-04T02:17:00.000Z'
Tags: ['V4', 'notion to md', 'test']
title: 'Notion Properties as Frontmatter'
draft: true
comments: 'true'
---

Transforming Properties

For more granular control over the value of a property, the transform option allows you to provide custom functions to process specific properties before they are added to the frontmatter. Each transform function receives the Notion property object and all page properties, returning the final string value.

The property name is case sensitive

import {
 NotionPageProperty,
 NotionPageProperties,
} from 'notion-to-md/types/notion';

const renderer = new MDXRenderer({
 frontmatter: {
 transform: {
 // Format dates in ISO format (YYYY-MM-DD)
 date: (property, _allProperties): string => {
 if (property.type !== 'date' || !property.date?.start) return '';
 return new Date(property.date.start).toISOString().split('T')[0];
 },

 // Convert tags to lowercase and return as JSON array string
 tags: (property, _allProperties): string => {
 if (property.type !== 'multi_select') return '';
 return JSON.stringify(
 property.multi_select.map((tag) => tag.name.toLowerCase()),
 );
 },

 // Generate slug from title property (assuming property named 'Name')
 slug: (_property, allProperties): string => {
 const titleProp = allProperties['Name'];
 if (!titleProp || titleProp.type !== 'title') return '';
 const title = titleProp.title.map((t) => t.plain_text).join('');
 return title
 .toLowerCase()
 .replace(/[^\w\s-]/g, '')
 .replace(/\s+/g, '-');
 },
 },
 },
});

This provides powerful customization without needing to override the entire frontmatter logic.

Fine-Tuning with a Custom Variable Resolver (Advanced)

Tip

A prerequisite going further would be having understanding of how one can modify any existing renderer plugin.

The renderer plugin uses frontmatter variable to resolve frontmatter values. You can customize this behavior by adding a custom variable resolver. This method is perfect for implementing unique formatting or transformation rules, allowing you complete control over how properties are processed and displayed.

Use Case: Formatting Tags for a Blog Post.

Assume you’re creating a blog and want your Notion “Tags” property (a multi-select field) to appear as a well-formatted list in the frontmatter. While the new transform option could handle formatting the tags array itself (e.g., converting to lowercase), if you need complete control over the final YAML output structure for all frontmatter, overriding the resolver is still the way to go.

import { MDXRenderer } from 'notion-to-md/plugins/renderer';

const renderer = new MDXRenderer();

// Customize frontmatter with a variable resolver
renderer.addVariable('frontmatter', async (_, context) => {
 const properties = context.pageProperties;

 // Extract title and tags
 const title = properties?.Name?.title?.[0]?.plain_text || 'No Title';
 const tags = properties?.Tags?.multi_select?.map((tag) => tag.name) || [];

 // Format tags as a YAML list
 const tagsList =
 tags.length > 0
 ? `tags:\n ${tags.map((tag: string) => `- ${tag}`).join('\n ')}`
 : '';

 // Return the custom frontmatter
 return `---
title: "${title}"
${tagsList}
---
`;
});

the output:

---
title: 'Notion Properties as Frontmatter'
tags:
 - V4
 - notion to md
 - test
---

oh and the best part is the configuration and the custom variable resolver works together.

Tip

Read more about the context we are using to access properties and other things.

Conclusion

The plugin system in notion-to-md v4 makes it easy to customize every aspect of the conversion process, ensuring that your content maintains its structure and metadata as it moves from Notion to your publishing platforms.

For more advanced customization, check out the guide on creating a renderer plugin from scratch.

Note

Share Your Use Case and Work

Have you created an interesting customization or workflow with notion-to-md? We’d love to hear about it! Consider sharing your experience by:

Creating a blog post in the notion-to-md blog section
Adding an entry to our plugin catalog if you’ve built a > reusable plugin
Joining our community discussions on GitHub

Your real-world examples can help others unlock the full potential of using Notion as a content source!

How to Handle Documents in Notion Using notion-to-md v4

Wed, 12 Mar 2025 00:00:00 +0000

When converting Notion pages to Markdown, dealing with embedded documents such as PDFs might be tricky. Unlike photos or plain text, PDFs include rich content that necessitates particular handling. This guide explains how notion-to-md v4 helps handling these documents at different levels.

Embedded PDFs or any media in Notion present several unique challenges:

Media Management: Media are stored on temporary Notion URLs that expire
Content Access: You may want to extract or process the PDF content itself
Embedded Experience: In some outputs (like websites), you might want to embed the PDF viewer

Media Handling Strategies

notion-to-md v4 offers three approaches:

Direct Strategy (Default)
- Simple: Uses original Notion URLs
- Advanced: Buffers media in memory for processing
Download Strategy
- Saves files to your local filesystem
Upload Strategy
- Uploads files to external storage (S3, Cloudinary, etc.)

To know more about each strategy, refer to the Media Handling Strategies guide.

In this guide, we’ll explore both the Direct Strategy (with buffering) and Download Strategy to process PDFs. Each approach has its advantages:

Direct Strategy with Buffering: Perfect for processing PDFs in memory without saving them to disk. Proves to be useful in serverless environment.
Download Strategy: Ideal when you need permanent local copies of the files.

Processing PDF Content

Let’s look at both approaches for extracting and processing PDF content.

Here is what our target page looks like:

Approach 1: Using Direct Strategy with Buffering

This approach processes PDFs directly in memory without saving them to disk:

Code using Direct Strategy with buffering

import { Client } from '@notionhq/client';
import { NotionConverter } from 'notion-to-md';
import { DefaultExporter } from 'notion-to-md/plugins/exporter';
import { MDXRenderer } from 'notion-to-md/plugins/renderer';
import pdf from 'pdf-parse';

// Initialize Notion client
const notion = new Client({
 auth: 'your-notion-api-key',
});

const renderer = new MDXRenderer();

// Customize how PDF blocks are processed
renderer.createBlockTransformer('pdf', {
 transform: async ({ block, utils }) => {
 // Access the buffer directly from the block
 if (block.buffer) {
 try {
 // Parse PDF directly from buffer
 const data = await pdf(block.buffer);

 // Extract first 1000 characters for preview
 const preview = data.text.slice(0, 1000).trim();

 // Get caption if available
 const caption =
 block.pdf.caption.length > 0
 ? block.pdf.caption[0].plain_text
 : 'Document Preview';

 // Format as collapsible preview with original URL
 return `
<details>
<summary>${caption}</summary>

\`\`\`text
${preview}...
\`\`\`

[View Full Document](${
 block.pdf.type === 'external'
 ? block.pdf.external.url
 : block.pdf.file.url
 })
</details>`;
 } catch (error) {
 console.error('Failed to process PDF:', error);
 return '[PDF Processing Failed]';
 }
 }

 // Fallback to URL if buffer is unavailable
 const pdfUrl =
 block.pdf.type === 'external'
 ? block.pdf.external.url
 : block.pdf.file.url;

 return `[PDF Document](${pdfUrl})`;
 },
});

const n2m = new NotionConverter(notion)
 .configureFetcher({
 fetchComments: true,
 fetchPageProperties: true,
 })
 // Configure Direct Strategy with buffering
 .useDirectStrategy({
 buffer: {
 enableFor: ['block'],
 includeBlockContentTypes: ['pdf'],
 maxBufferSize: 10 * 1024 * 1024, // 10MB limit
 },
 })
 .withRenderer(renderer)
 .withExporter(
 new DefaultExporter({
 outputType: 'file',
 outputPath: './output.md',
 }),
 );

(async () => {
 try {
 await n2m.convert('page-id');
 console.log('✓ Successfully converted page with buffered PDF processing!');
 } catch (error) {
 console.error('Conversion failed:', error);
 }
})();

Approach 2: Using Download Strategy

When you need to save PDFs locally and process them:

Code using Download Strategy

import { Client } from '@notionhq/client';
import { NotionConverter } from 'notion-to-md';
import { DefaultExporter } from 'notion-to-md/plugins/exporter';
import { MDXRenderer } from 'notion-to-md/plugins/renderer';
import pdf from 'pdf-parse';
import fs from 'fs/promises';
import path from 'path';

// Initialize Notion client
const notion = new Client({
 auth: 'your-notion-api-key',
});

const renderer = new MDXRenderer();

// Customize how PDF blocks are processed
renderer.createBlockTransformer('pdf', {
 transform: async ({ block, manifest }) => {
 // @ts-ignore
 const pdfBlock = block.pdf;

 // Get media information from manifest
 const mediaEntry = manifest.media?.getEntry(block.id);
 if (!mediaEntry) {
 return `[PDF File Not Found]`;
 }

 // Get the local path and transformed URL from media info
 const { localPath, transformedPath } = mediaEntry.mediaInfo;

 if (!localPath) {
 return `[PDF File Not Found]`;
 }
 console.log(mediaEntry, path.basename(localPath || ''));

 // Read and parse the PDF
 const dataBuffer = await fs.readFile(localPath);
 const data = await pdf(dataBuffer);

 // Extract first 1000 characters for preview
 const preview = data.text.slice(0, 1000).trim();

 // Format as collapsible preview with link
 return `
<details>
<summary>${pdfBlock.caption.length > 0 ? pdfBlock.caption[0].plain_text : 'Document Preview'}</summary>

\`\`\`text
${preview}...
\`\`\`

[View Full Document](${transformedPath})
</details>
`;
 },
});

const n2m = new NotionConverter(notion)
 .configureFetcher({
 fetchComments: true,
 fetchPageProperties: true,
 })
 .downloadMediaTo({
 outputDir: './public/documents',
 transformPath: (localPath) => `/documents/${path.basename(localPath)}`,
 })
 .withRenderer(renderer)
 .withExporter(
 new DefaultExporter({
 outputType: 'file',
 outputPath: './output.md',
 }),
 );

(async () => {
 try {
 await n2m.convert('page-id');
 console.log('✓ Successfully converted page with downloaded PDFs!');
 } catch (error) {
 console.error('Conversion failed:', error);
 }
})();

Tip

Choose the Direct Strategy with buffering when you only need to process the PDF content and don’t need to store the files. Use the Download Strategy when you need permanent local copies or want to serve the PDFs from your own server.

Markdown Output

Embedding PDFs

Say you want some interactivity in your web-based content such as allowing people to browse, scroll, or search within PDFs directly on your website. Instead of just linking to a file, embedding a PDF creates a seamless reading experience that keeps users interested without diverting them away.

Let’s start by creating a PDF viewer component:

src/components/PDFViewer.tsx

// for example purpose we'll stick with iframe, you can use
// modern packages like react-pdf-viewer, react-pdf etc...
export function PDFViewer({ url }: { url: string }) {
 return (
 <iframe
 src={url}
 style={{ width: "100%", height: "750px", border: "none" }}
 />
 );
}

You can use this component with either strategy:

renderer.createBlockTransformer('pdf', {
 transform: async ({ block, manifest, utils }) => {
 // For Direct Strategy with buffering
 if (block.buffer) {
 // You could convert the buffer to a data URL
 const base64 = block.buffer.toString('base64');
 return `
<PDFViewer url="data:application/pdf;base64,${base64}" />
`;
 }

 // For Download Strategy
 const mediaEntry = manifest.media?.getEntry(block.id);
 if (mediaEntry?.mediaInfo.transformedPath) {
 return `
<PDFViewer url="${mediaEntry.mediaInfo.transformedPath}" />
`;
 }

 // Fallback to original URL
 const pdfUrl =
 block.pdf.type === 'external'
 ? block.pdf.external.url
 : block.pdf.file.url;

 return `
<PDFViewer url="${pdfUrl}" />
`;
 },
 imports: [`import { PDFViewer } from '@/components/PDFViewer';`],
});

Note

The example is tested in nextjs with mdx integration

Here is your output MDX content:

---
Created: '2025-01-04T02:17:00.000Z'
Tags: ['V4', 'notion to md', 'test']
PublishURL: '/page-1'
Name: 'Handling PDF using Notion to md v4'
---

import { PDFViewer } from '@/components/PDFViewer';

# Embedded pdf

I'll put up my resume for this example (I'm looking for opportunities 😅)

<PDFViewer url="data:application/pdf;base64,JVBERi0xLjcKCjEgMCBvYmogICUgZW50..." />

and this is how it’ll show up in browser:

Conclusion:

With notion-to-md v4, managing PDFs is more flexible than ever. You can:

Use the Direct Strategy with buffering for efficient in-memory processing
Use the Download Strategy for permanent local storage
Extract content from PDFs for better SEO and accessibility
Create interactive PDF experiences in your web content

Whether you need quick in-memory processing or permanent local storage, notion-to-md v4 provides the tools to handle PDFs effectively.

Note

Share Your Use Case and Work

Have you created an interesting customization or workflow with notion-to-md? We’d love to hear about it! Consider sharing your experience by:

Creating a blog post in the notion-to-md blog section
Adding an entry to our plugin catalog if you’ve built a reusable plugin
Joining our community discussions on GitHub

Your real-world examples can help others unlock the full potential of using Notion as a content source!

How to Convert Notion Comments to Markdown Footnotes with notion-to-md v4

Tue, 11 Mar 2025 00:00:00 +0000

In this guide, we’ll explore how to modify the default renderer to transform Notion comments into proper Markdown footnotes.

Why Convert Comments to Footnotes?

Notion comments frequently offer important explanations, references, or critical thoughts that improve your writing. You may make sure that this information is preserved when you publish or distribute your work by turning them into Markdown footnotes. For authors, developers, and bloggers that use Notion as a content management system, this method is perfect.

Prerequisites

Before starting, make sure you have:

notion-to-md v4 installed: npm install notion-to-md@alpha
Notion API token with access to your content and can read comments
You understand block transformation and variable system.

Here is the test notion page:

Step 1: Set Up Your Project

First, let’s create a basic project structure:

import { Client } from '@notionhq/client';
import { NotionConverter } from 'notion-to-md';
import { MDXRenderer } from 'notion-to-md/plugins/renderer/mdx';
import { DefaultExporter } from 'notion-to-md/plugins/exporter';

// Initialize Notion client
const notion = new Client({
 auth: 'your-notion-api-key',
});

// Using the default renderer that ships with package (we'll modify this)
const renderer = new MDXRenderer({ frontmatter: true });

// Set up the converter with our renderer
const n2m = new NotionConverter(notion)
 .withRenderer(renderer)
 .withExporter(new DefaultExporter({
 outputType: 'file',
 outputPath: './output.md'
 }));

Step 2: Enable Comment Fetching

By default, notion-to-md doesn’t fetch comments from the Notion API. We need to enable this first:

const n2m = new NotionConverter(notionClient)
 .configureFetcher({
 fetchComments: true, // This is important!
 fetchPageProperties: true
 });

Step 3: Modify the Template to Include Footnotes

The default MD/MDX renderer plugin template doesn’t include a dedicated section for footnotes. Let’s update it to add a footnotes section at the end of the document:

renderer.setTemplate(`{{{frontmatter}}}

{{{imports}}}

{{{content}}}

{{{footnotes}}}`); //footnotes placeholder

// Add a variable to collect footnotes
renderer.addVariable('footnotes', async (_, context) => {
 // through out the rendering process all the comments will be collected in the footnotes variable
 // at the end this resolver will be called to format the collected footnotes as a section and substitute them in the template
 const footnotes = context.variableData.get('footnotes') || [];
 if (!footnotes.length) return '';

 return `\n---\n## Footnotes\n\n${footnotes.join('\n')}\n`;
});

Tip

know more about context

Here, we’re:

Adding a {{{footnotes}}} placeholder to the template where our footnotes will appear.
Creating a variable resolver that formats the collected footnotes as a section, the output of resolver is substituted in the template.

Step 4: Modify Block Transformers to Handle Comments

Now, we need to intercept blocks with comments and transform them appropriately. We’ll focus on paragraph blocks for this tutorial, as they’re most commonly commented on:

// Create a custom transformer for paragraphs
renderer.createBlockTransformer('paragraph', {
 transform: async ({ block, utils, variableData }) => {
 // Process rich text as usual
 const text = await utils.transformRichText(block.paragraph.rich_text);

 // Check if the block has comments
 if (block.comments && block.comments.length > 0) {
 // Get the current footnotes collection or initialize it
 const footnotes = variableData.get('footnotes') || [];
 const footnoteIndex = footnotes.length + 1;

 // Add comment text to footnotes variable
 const commentText = block.comments
 .map(comment => comment.rich_text.map(rt => rt.plain_text).join(''))
 .join(' ');

 footnotes.push(`[^${footnoteIndex}]: ${commentText}`); // collecting comments in the footnotes variable
 variableData.set('footnotes', footnotes);

 // Return paragraph with footnote reference
 return `${text} [^${footnoteIndex}]\n\n`;
 }

 // Return normal paragraph
 return `${text}\n\n`;
 }
});

This transformer does several important things:

Processes the paragraph text normally
Checks if the block has comments
If it does, creates a footnote reference in the paragraph
Adds the comment text to our footnotes collection

Step 5: Putting It All Together

Here’s the complete code that combines all the steps:

import { Client } from "@notionhq/client";
import { NotionConverter } from "notion-to-md";
import { DefaultExporter } from "notion-to-md/plugins/exporter";
import { MDXRenderer } from "notion-to-md/plugins/renderer";

// Initialize Notion client
const notion = new Client({
 auth: "your-notion-api-key",
});

// Using the default renderer that ships with package (we'll modify this)
const renderer = new MDXRenderer({ frontmatter: true });

renderer.setTemplate(`{{{frontmatter}}}

{{{imports}}}

{{{content}}}

{{{footnotes}}}`); //footnotes placeholder

// Add a variable to collect footnotes
renderer.addVariable("footnotes", async (_, context) => {
 const footnotes = context.variableData.get("footnotes") || [];
 if (!footnotes.length) return "";

 return `\n---\n## Footnotes\n\n${footnotes.join("\n")}\n`;
});

// Create a custom transformer for paragraphs
renderer.createBlockTransformer("paragraph", {
 transform: async ({ block, utils, variableData }) => {
 const text = await utils.transformRichText(block.paragraph.rich_text);

 // Check if the block has comments
 if (block.comments && block.comments.length > 0) {
 // Get the current footnotes collection or initialize it
 const footnotes = variableData.get("footnotes") || [];
 const footnoteIndex = footnotes.length + 1;

 // Add comment text to footnotes variable
 const commentText = block.comments
 .map((comment) => comment.rich_text.map((rt) => rt.plain_text).join(""))
 .join(" ");

 footnotes.push(`[^${footnoteIndex}]: ${commentText}`);
 variableData.set("footnotes", footnotes);

 // Return paragraph with footnote reference
 return `${text} [^${footnoteIndex}]\n\n`;
 }

 // Return normal paragraph
 return `${text}\n\n`;
 },
});

// Set up the converter with our renderer
const n2m = new NotionConverter(notion)
 .configureFetcher({
 fetchComments: true,
 fetchPageProperties: true,
 })
 .withRenderer(renderer)
 .withExporter(
 new DefaultExporter({
 outputType: "file",
 outputPath: "./output.md",
 }),
 );

(async () => {
 try {
 await n2m.convert("your-page-id");
 console.log("✓ Successfully converted page with comments as footnotes!");
 } catch (error) {
 console.error("Conversion failed:", error);
 }
})();

Example Output

With this setup, a Notion page with comments will convert to Markdown that looks like this:

---
Created: "2025-01-04T02:17:00.000Z"
Tags: ["V4", "notion to md", "test"]
PublishURL: "/page-1"
Name: "Notion comment as Footnotes guide"
---

# My Notion Content

This is a paragraph with a comment attached. [^1]

Another paragraph with multiple comments. [^2]

Here is a comment on a phrase in the third paragraph. [^3]


---
## Footnotes

[^1]: This paragraph needs to be updated
[^2]: Comment 1 Follow up comment (2) https://github.com/join-escape/exporto-playground
[^3]: This is a very specific comment

Improvements and Advanced Customization

Reusable Comment Processing Function

Optimize your code by reusing the comment-handling logic across block types:

// Create a utility function for handling comments
function addCommentsAsFootnotes(text, block, variableData) {
 if (!block.comments || block.comments.length === 0) {
 return text;
 }

 const footnotes = variableData.get('footnotes') || [];
 const footnoteIndex = footnotes.length + 1;

 // Process comment text
 const commentText = block.comments
 .map(comment => comment.rich_text.map(rt => rt.plain_text).join(''))
 .join(' ');

 footnotes.push(`[^${footnoteIndex}]: ${commentText}`);
 variableData.set('footnotes', footnotes);

 // Return text with footnote reference
 return `${text} [^${footnoteIndex}]`;
}

// Now we can use this utility with any block transformer
renderer.createBlockTransformer('heading_1', {
 transform: async ({ block, utils, variableData }) => {
 const text = await utils.transformRichText(block.heading_1.rich_text);
 const processedText = addCommentsAsFootnotes(text, block, variableData);
 return `# ${processedText}\n\n`;
 }
});

renderer.createBlockTransformer('bulleted_list_item', {
 transform: async ({ block, utils, variableData }) => {
 const text = await utils.transformRichText(block.bulleted_list_item.rich_text);
 const processedText = addCommentsAsFootnotes(text, block, variableData);
 return `- ${processedText}\n`;
 }
});

// ... and so on for other block types

Handling Nested Blocks with Comments

If you have comments on nested blocks (like in toggle lists), you’ll need to pass the context through to child blocks:

renderer.createBlockTransformer('toggle', {
 transform: async ({ block, utils, variableData, metadata }) => {
 const summary = await utils.transformRichText(block.toggle.rich_text);
 const processedSummary = addCommentsAsFootnotes(summary, block, variableData);

 // Process children with the same context to maintain footnote numbering
 const childContent = block.children?.length
 ? await Promise.all(
 block.children.map(child => utils.processBlock(child, metadata))
 )
 : [];

 return `<details>
 <summary>${processedSummary}</summary>
 ${childContent.join('\n')}
</details>\n\n`;
 }
});

Conclusion

With notion-to-md v4’s flexible plugin system, you can easily transform Notion comments into useful footnotes in your Markdown output. This approach preserves important context and additional information from your collaborative work in Notion when publishing or sharing content.

For more ways to customize your Notion-to-Markdown conversion, check out the official documentation on how to modify renderer plugins. You can also explore other block transformers to customize how different Notion blocks are rendered.

Note

Share Your Use Case and Work

Have you created an interesting customization or workflow with notion-to-md? We’d love to hear about it! Consider sharing your experience by:

Creating a blog post in the notion-to-md blog section
Adding an entry to our plugin catalog if you’ve built a > reusable plugin
Joining our community discussions on GitHub

Your real-world examples can help others unlock the full potential of using Notion as a content source!