> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mark2notion.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Notion to Markdown

> Convert Notion page content to Markdown format

## Overview

The notion-to-markdown endpoint retrieves content from a Notion page and converts it to Markdown format. This is useful for exporting Notion content, creating backups, or integrating Notion content with other Markdown-based systems.

## Supported Block Types

The converter supports a comprehensive set of Notion block types:

### Text Blocks

* **Paragraphs**: Standard text blocks
* **Headings**: H1, H2, H3 (converted to `#`, `##`, `###`)
* **Quotes**: Blockquote blocks
* **Callouts**: Notion callouts (converted to GFM-style alerts when possible)
* **Code Blocks**: With language syntax support

### Lists

* **Bulleted Lists**: Converted to `-` items
* **Numbered Lists**: Converted to `1.` items
* **To-do Lists**: Converted to `- [ ]` or `- [x]` checkboxes
* **Nested Lists**: Full nesting support

### Media & Embeds

* **Images**: Converted to `![alt](url)` format
* **External Images**: Both uploaded and external images supported

### Advanced Blocks

* **Tables**: Full table support with headers
* **Dividers**: Converted to `---`
* **Child Pages**: Referenced in the output
* **Child Databases**: Referenced in the output

### Text Formatting & Colors

All rich text formatting from Notion is preserved in the Markdown output:

* **Bold**: Converted to `**bold**`
* **Italic**: Converted to `*italic*`
* **Code**: Converted to `` `code` ``
* **Strikethrough**: Converted to `~~strikethrough~~`
* **Links**: Converted to `[text](url)`
* **Colors**: Converted to HTML `<span>` tags with inline styles

**Color Support:**

Notion text colors are converted to HTML spans with inline CSS styles. This allows the colors to be preserved when the Markdown is rendered in systems that support HTML.

**Supported Colors:**

* `red`, `blue`, `green`, `yellow`, `orange`, `purple`, `pink`, `gray`, `brown`

**Example:**

```markdown theme={null}
This is <span style="color: red">red text</span> and <span style="color: blue">blue text</span>.
```

**Features:**

* Works with all block types (paragraphs, headings, lists, quotes, etc.)
* Can be combined with other formatting (bold, italic, code, etc.)
* Multiple colors can be used within a single block

**Limitations:**

* Background colors (e.g., `red_background`) are not currently supported
* Colors are exported as HTML, which requires the Markdown renderer to support inline HTML

## Request

<ParamField header="x-api-key" type="string" required>
  Your Mark2Notion API key
</ParamField>

<ParamField body="notionToken" type="string">
  Your Notion integration token. Optional when your workspace is connected via OAuth in the dashboard. Pass this if you prefer to authenticate with a manual integration token instead. See [Using a Manual Notion Token](/quickstart#using-a-manual-notion-token-advanced).
</ParamField>

<ParamField body="pageId" type="string" required>
  The URL or page ID of the Notion page to convert. Pass the full `notion.so` page URL or just the page ID — both are accepted.
</ParamField>

## Response

<ResponseField name="status" type="string">
  Will be "success" for successful requests
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data">
    <ResponseField name="markdown" type="object">
      An object containing the Markdown representation of the page content

      <Expandable title="markdown">
        <ResponseField name="parent" type="string">
          The Markdown content of the main/parent page
        </ResponseField>

        <ResponseField name="[childPageTitle]" type="string">
          If the page has child pages, each child page will be included as a separate property with the child page title as the key and its Markdown content as the value
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="pageId" type="string">
      The ID of the page that was converted
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://api.mark2notion.com/api/notion-to-markdown" \
    -H "Content-Type: application/json" \
    -H "x-api-key: YOUR_API_KEY" \
    -d '{
      "pageId": "https://notion.so/Your-Page-Title-abc123def456"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.mark2notion.com/api/notion-to-markdown', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'YOUR_API_KEY'
    },
    body: JSON.stringify({
      pageId: 'https://notion.so/Your-Page-Title-abc123def456'
    })
  });

  const data = await response.json();
  console.log(data.data.markdown.parent); // Parent page content
  // If there are child pages, they'll be available as separate properties:
  // console.log(data.data.markdown['Child Page Name']);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.mark2notion.com/api/notion-to-markdown',
      headers={
          'Content-Type': 'application/json',
          'x-api-key': 'YOUR_API_KEY'
      },
      json={
          'pageId': 'https://notion.so/Your-Page-Title-abc123def456'
      }
  )

  data = response.json()
  print(data['data']['markdown']['parent'])  # Parent page content
  # If there are child pages, they'll be available as separate keys:
  # print(data['data']['markdown']['Child Page Name'])
  ```
</CodeGroup>

<ResponseExample>
  ````json Example Response (Simple Page) theme={null}
  {
    "status": "success",
    "data": {
      "markdown": {
        "parent": "# My Page Title\n\nThis is a paragraph with **bold** text and *italic* text.\n\n## Subheading\n\n- List item 1\n- List item 2\n  - Nested item\n\n---\n\n```javascript\nconsole.log('Code block');\n```\n\n> This is a quote block\n\n| Column 1 | Column 2 |\n|----------|----------|\n| Cell 1   | Cell 2   |"
      },
      "pageId": "abc123def456"
    }
  }
  ````

  ```json Example Response (Page with Child Pages) theme={null}
  {
    "status": "success",
    "data": {
      "markdown": {
        "parent": "# Main Page\n\nThis is the parent page content.\n\n> 📘 Note\n> This is a callout\n",
        "Child Page 1": "## Child Page Content\n\nThis is content from the first child page.\n",
        "Another Child": "## Another Child Page\n\nContent from another child page.\n"
      },
      "pageId": "abc123def456"
    }
  }
  ```
</ResponseExample>

## Error Responses

<Card title="Handle Errors" icon="triangle-exclamation" href="/errors">
  Understand error responses and how to handle them.
</Card>

### Common Errors

<AccordionGroup>
  <Accordion title="Invalid Notion Token">
    **Status Code**: 401 Unauthorized

    The Notion token provided is invalid or expired. Make sure you're using a valid integration token.
  </Accordion>

  <Accordion title="Page Not Found">
    **Status Code**: 404 Not Found

    The page ID doesn't exist or your integration doesn't have access to it. Verify the page ID and ensure the page is shared with your integration.
  </Accordion>

  <Accordion title="Access Denied">
    **Status Code**: 403 Forbidden

    Your Notion integration doesn't have permission to access this page. Share the page with your integration in Notion.
  </Accordion>
</AccordionGroup>

## Response Structure

The `markdown` field in the response is an object that separates parent and child page content:

* **`parent`**: Contains the main page's Markdown content
* **`[Child Page Title]`**: If the page has child pages, each will be a separate property named after the child page title, containing that child's Markdown content

This structure allows you to:

* Access the main content via `data.markdown.parent`
* Iterate over child pages if they exist
* Maintain the hierarchy of your Notion page structure

## Usage Notes

<Info>
  Each notion-to-markdown request counts as 1 API call against your quota, regardless of the page size or number of child pages.
</Info>

<Tip>
  The endpoint returns standard Markdown that's compatible with GitHub Flavored Markdown (GFM) and most Markdown processors.
</Tip>

<Warning>
  Make sure your Notion workspace is connected in the dashboard and has access to the page you want to convert.
</Warning>

## Setup Guide

Connect your Notion workspace in the [dashboard](https://dashboard.mark2notion.com) via OAuth. Then pass your target page as a URL or page ID in the `pageId` field — no manual integration tokens required.

## Use Cases

* **Content Backup**: Export Notion pages to Markdown for backup purposes
* **Static Site Generation**: Convert Notion content to Markdown for static site generators
* **Documentation Sync**: Keep documentation in Notion and export to Markdown-based systems
* **Content Migration**: Move content from Notion to other platforms
* **Version Control**: Track Notion content changes in Git using Markdown format