# Content Blocks



This guide explains how to fetch block content, convert it into different shapes, and render it. It assumes you already initialised `NotionCMS`.

## Fetch raw blocks

```
typescript
const blocks = await notion.getPageContentRaw("<page-id>")
```

- Defaults to recursive fetching (`recursive = true`). Set `recursive: false` to fetch only the first level.
- Blocks include children and media URLs automatically processed by `FileManager`.


## Simple block objects

```
typescript
import { convertBlocksToSimple } from "@mikemajara/notion-cms"

const simpleBlocks = await convertBlocksToSimple(blocks)
```

`SimpleBlock` items include:

- `id`, `type`, `content`, `hasChildren`, optional `children`.
- Table helpers (`SimpleTableBlock`, `SimpleTableRowBlock`) expose structured data.


### Media URLs and FileManager

When you provide a `FileManager`, media URLs are re-written using your configured strategy:

```
typescript
const simpleBlocks = await convertBlocksToSimple(blocks, {
  fileManager: myFileManager
})
```

## Advanced block objects

```
typescript
import { convertBlocksToAdvanced } from "@mikemajara/notion-cms"

const advancedBlocks = await convertBlocksToAdvanced(blocks)
```

- Preserves captions as both plain text and markdown.
- Includes media expiry, callout icons, table row cell detail, columns, synced blocks, child entries, etc.
- Accepts `mediaUrlResolver` to customise media handling:


```
typescript
const advancedBlocks = await convertBlocksToAdvanced(blocks, {
  mediaUrlResolver: async (block, field) => {
    if (block.type === "image") {
      return await myCdn.store(field.file.url)
    }
    return field.file?.url ?? ""
  }
})
```

## Markdown rendering

```
typescript
import { blocksToMarkdown } from "@mikemajara/notion-cms"

const markdown = blocksToMarkdown(blocks, {
  includeImages: true,
  listBullets: "-"
})
```

- Uses `groupConsecutiveListItems` internally for correct nesting.
- Options let you tweak list symbols, heading depth, or whether to emit image references.


## HTML rendering

```
typescript
import { blocksToHtml } from "@mikemajara/notion-cms"

const html = blocksToHtml(blocks, {
  classPrefix: "notion-"
})
```

- Respects `classPrefix` for styling rich-text annotations.
- Outputs semantic tags (`<h1>`, `<ul>`, `<code>`, etc.).


## Combining pipelines

Common flows:

1. Fetch raw blocks via `getPageContentRaw`.
2. Convert to simple or advanced structures for custom UIs.
3. Generate markdown or HTML for static rendering or fallback content.


You can also process the raw blocks from Notion (without `getPageContentRaw`) if you already have them from another source. The converters accept any `ContentBlockRaw[]`.

## Handling pagination manually

`PageContentService` already iterates through API cursors, but if you need fine-grained control, you can call Notion’s API directly and then pass the results into these helpers. Be sure to enrich media URLs, as `PageContentService` does, before converting to avoid short-lived Notion links.