npm package: @se-studio/markdown-renderer
Description: Markdown renderer for Contentful content
Latest version: 1.0.89

# @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.
- **HTML components**: `IBaseHtmlComponent` entries contribute `markdownContent` to exports when `excludeFromSearch` is false; `isHero` blocks are ordered first (same as `CmsContent`).
- **Frontmatter Generation**: meaningful YAML frontmatter for exported content.

## Installation

```bash
pnpm add @se-studio/markdown-renderer
```

## Usage

### Basic Export & Conversion

```typescript
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

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

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

## License

MIT