@se-studio/markdown-renderer

Utilities for converting Contentful content into Markdown format. This package provides tools to export pages, articles, and custom types from Contentful and convert them into structured Markdown, suitable for LLM consumption or static site generation.

Features

• Content Export: Fetch content from Contentful (Pages, Articles, Custom Types) with full context.
• Markdown Conversion: Convert structured Contentful data into clean, readable Markdown.
• Rich Text Support: Automatically converts Contentful Rich Text fields to Markdown.
• Component & Collection Handling: Recursively processes nested components and collections.
• Frontmatter Generation: meaningful YAML frontmatter for exported content.

Installation

pnpm add @se-studio/markdown-renderer

Usage

Basic Export & Conversion

import { createContentfulClient } from '@se-studio/contentful-rest-api';
import { MarkdownExporter, MarkdownConverter } from '@se-studio/markdown-renderer';

// 1. Setup Client and Exporter
const config = {
  spaceId: process.env.CONTENTFUL_SPACE_ID!,
  accessToken: process.env.CONTENTFUL_ACCESS_TOKEN!,
  environment: 'master'
};

const exporter = new MarkdownExporter(config);
const converter = new MarkdownConverter();

// 2. Fetch Content
// Supported types: 'page', 'article', 'blogPost', 'customType'
const contentData = await exporter.fetchContent('page', 'home');

if (contentData) {
  // 3. Convert to Markdown
  const markdown = converter.convert(contentData, {
    contentContext: contentData.context,
    config: config
  });

  console.log(markdown);
}

API Reference

MarkdownExporter

Handles fetching data from Contentful and preparing the context.

constructor(config: ContentfulConfig, preview?: boolean)

• config: Contentful configuration object.
• preview: Boolean to enable Preview API (default: false).

fetchContent(type, slug, params?)

Fetches content by slug and returns a ContentData object.

• type: 'page' | 'article' | 'blogPost' | 'customType'
• slug: The slug of the entry.
• params: Optional parameters (e.g., { articleType: 'blog' }).

MarkdownConverter

Handles the transformation of ContentData into a Markdown string.

convert(contentData, context)

• contentData: The data object returned by MarkdownExporter.
• context: Context object containing contentContext and config.

resolveMarkdownParams and route options

When building a markdown API route (e.g. /api/markdown/[...params]), use resolveMarkdownParams(slugParams, options) to map path segments to content type and slug. The resolver uses canonical first segments: articles, tags, people. Any other first segment is treated as a page (full path as slug). Path mapping from public URLs (e.g. /learning-hub/blog) to these canonical segments is the responsibility of markdown rewrites in each app's next.config.

Options:

• articlesBaseIsPage: When true, a single segment articles resolves as a page with slug "articles".
• enablePrimaryTagPartOfSlug: When true, article paths use four segments: articles/:type/:tag/:slug.
• peopleCustomType: Contentful custom type for person entries (default 'people'). Use e.g. 'team' when your app uses a different content type.

Types

interface ContentData {
  contentType: 'page' | 'article' | 'customType';
  data: IBasePage | IBaseArticle | IBaseCustomType;
  context: IContentContext;
}

interface MarkdownConverterContext {
  contentContext: IContentContext;
  config: ContentfulConfig;
}

License

MIT