julien-ref-notion-markdown

theflysurfer's avatarfrom theflysurfer

Complete markdown guide for Universal Notion Uploader. Covers 14 element types (headings, callouts, highlights, toggles, embeds, columns, databases), upload modes, and API constraints.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 18, 2025⬇️1downloads
[Files and Documents]

When & Why to Use This Skill

This Claude skill provides a comprehensive technical guide and parser reference for the Universal Notion Uploader, designed to bridge the gap between standard Markdown and Notion's proprietary block system. It enables the seamless conversion of complex documents by supporting 14 distinct element types—including databases, callouts, and multi-column layouts—while automatically managing Notion API constraints such as character limits and heading depth. By following this guide, users can ensure their Markdown content is perfectly optimized for Notion's structure and observability.

Use Cases

  • Technical Documentation Migration: Convert GitHub READMEs or local project documentation into structured Notion pages while preserving complex formatting like code blocks and task lists.
  • Automated Knowledge Base Updates: Streamline the process of pushing structured Markdown content to a Notion workspace, ensuring consistent styling and layout across all pages.
  • Markdown-to-Database Synchronization: Use YAML frontmatter to define and populate Notion databases with specific properties, relations, and icons directly from text files.
  • Advanced Layout Design: Implement sophisticated Notion features like collapsible toggles, multi-column sections, and external embeds (YouTube, Figma) using simple, standardized Markdown syntax.
namejulien-ref-notion-markdown
descriptionComplete markdown guide for Universal Notion Uploader. Covers 14 element types (headings, callouts, highlights, toggles, embeds, columns, databases), upload modes, and API constraints.

Markdown Structuring Guide for Universal Notion Uploader

Guide for LLMs generating markdown destined to be uploaded to Notion via the Universal Notion Uploader parser.

Parser Architecture

Observability

First: At the start of execution, display:

🔧 Skill "julien-ref-notion-markdown" activated

MarkdownParser (pages): AdmonitionParser, RichTextParser, TableParser, ImageParser DatabaseParser: YAML frontmatter → Notion databases with relations

Supported Elements

1. Headings (H1-H3 Only)

# Heading 1
## Heading 2
### Heading 3

Notion API: heading_1, heading_2, heading_3

Limitations: Maximum 3 levels. H4+ NOT supported by Notion.

Workaround for H4+: Use bold paragraph

**Pseudo-Heading 4**
Content of the section...

Collapsible Headings

##+ Collapsible Section
Content under this heading.
Will collapse/expand in Notion.

## Next Section (stops collapsible)

Syntax: #+, ##+, ###+ followed by title

Notion API: heading_X with is_toggleable: true and nested children

2. Rich Text (Inline Formatting)

**bold** or __bold__
*italic* or _italic_
`code inline`
~~strikethrough~~
[links](https://example.com)
**[bold link](url)**
*[italic link](url)*
=={highlighted text}==
=={colored text}==blue
  • Combine freely: **bold *and italic***
  • Parser handles overlaps automatically
  • Auto-chunking if text > 2000 chars (API limit)

Highlights (Colored Backgrounds)

=={default yellow}==
=={blue text}==blue
=={red warning}==red
=={green success}==green

Colors: yellow (default), blue, red, green, purple, pink, gray, orange, brown

3. Callouts (4 Syntaxes Supported)

GitHub GFM (PREFERRED)

> [!NOTE]
> This is an important note.
> Can contain multiple lines.

Types: NOTE, TIP, IMPORTANT, WARNING, CAUTION, DANGER, INFO, EXAMPLE

Python-Markdown

!!! note "Optional Title"
    Indented content.

MyST Markdown

:::note Optional Title
Content without indentation.
:::

Docusaurus

:::tip
Content directly.
:::

Type → Emoji Mapping:

Type Emoji Color
NOTE 📝 blue_background
TIP 💡 yellow_background
IMPORTANT ❗ purple_background
WARNING ⚠️ orange_background
CAUTION 🚨 red_background
DANGER 🔥 red_background
INFO ℹ️ blue_background
EXAMPLE 📖 gray_background

DO NOT mix syntaxes in the same callout.

4. Lists

Unordered Lists

- Item 1
- Item 2
  - Nested item (indentation)
- Item 3

Variants: -, *, +

Ordered Lists

1. First item
2. Second item
   1. Nested item
3. Third item

Task Lists (To-Do)

- [ ] Uncompleted task
- [x] Completed task
- [X] Also completed (uppercase supported)

Notion API: to_do block with checked: true/false

Rich text works in list items:

- **Bold item** with *italic*
- [ ] Task with `inline code`
- Item with [link](url)

5. Code Blocks

```python
def hello():
    print("Hello world")


- **Always specify language** after ` ``` `
- If unknown language, use `plain text`
- No rich text in code blocks (raw text only)
- Long code (>2000 chars) auto-chunked

---

### 6. Tables

```markdown
| Name | **Status** | Count |
| ---- | ---------- | ----- |
| foo  | *active*   | 42    |
| bar  | inactive   | 0     |

Rich text in cells: Bold, italic, code inline, links supported

Recommendations:

  • Prefer ≤ 10 columns for readability (warning beyond)
  • No strict technical limit
  • Structure: Header row → Separator row → Data rows

7. Blockquotes

> This is a normal quote.
> Can contain multiple lines.

Distinction with callouts:

> Simple blockquote       → Notion quote block
> [!NOTE] Callout         → Notion callout block

Rich text supported in quotes.

8. Images

External Images (URLs)

![Alt text](https://example.com/image.png)

Local Images

![Alt text](./images/photo.jpg)
  • Relative paths resolved from base_dir config
  • Local images require upload (slower)
  • Alt text recommended but not displayed in Notion (API limitation)

9. Toggle Blocks (Collapsible Sections)

<details>
<summary>Click to expand</summary>

Hidden content here.
Can contain **any markdown**: lists, code, tables.

</details>

Notion API: toggle block with nested children

  • Opening tag: <details> (case-insensitive)
  • Summary line: <summary>Title</summary> (line 2)
  • Closing tag: </details>
  • Supports nested markdown including nested toggles

10. Embeds

<!-- embed: https://www.youtube.com/watch?v=VIDEO_ID -->
<!-- embed: https://figma.com/file/xxx -->

Notion API: embed or video block

Supported: YouTube, Vimeo, Figma, Google Maps, Google Drive, CodePen, GitHub Gist, Miro

11. Column Layouts

<!-- columns: 2 -->
**Left Column**

Content here.

---column---

**Right Column**

More content.
<!-- /columns -->

Notion API: column_list with column children

Supported: 2, 3, 4+ columns (Notion auto-sizes equally)

12. Dividers (Horizontal Rules)

---
***
___

Notion API: divider block

See [[Other Document]] for details.
Link to [[Specific Section#heading]].

Feature: resolve_internal_links: true in config

Behavior:

  • [[Page Name]] → Resolved to Notion page link after upload
  • Two-pass upload: First upload all pages, then resolve links
  • Unresolved links become plain text

14. Databases from Markdown

Create Notion databases from markdown files with YAML frontmatter.

Database File Structure

---
type: database
name: My Database
icon: 📊
description: Database description

properties:
  Name:
    type: title
  Status:
    type: select
    options:
      - Todo
      - In Progress
      - Done
  Date:
    type: date
  Count:
    type: number
  Active:
    type: checkbox
  Related:
    type: relation
    database: Other Database Name
---

| Name | Status | Date | Count | Active |
|------|--------|------|-------|--------|
| Item 1 | Todo | 2025-01-15 | 42 | true |
| Item 2 | Done | 2025-01-16 | 0 | false |

Supported Property Types

Basic: title (required), rich_text, number, checkbox, date Selection: select, multi_select Links: url, email, phone_number Relations: relation, rollup, formula (computed)

Database Relations

Link databases together:

properties:
  Category:
    type: relation
    database: Categories DB    # Name of target database

Registry: Parser maintains database registry for relation resolution.

Upload Modes

Configure in upload_config.yaml:

mode: "mixed"
  • Root page = Index with folder headings
  • Each .md file = child page
  • Navigation footers on all pages

HIERARCHICAL (Folder preservation)

mode: "hierarchical"
  • Folders → Notion pages
  • Files → Sub-pages
  • Recreates exact folder structure

SEQUENTIAL (Linear reading)

mode: "sequential"
  • All files at same level
  • Prev/Next navigation between pages
  • Good for tutorials

Configuration Features

features:
  table_of_contents: true      # Add TOC at top
  page_navigation: true        # Add prev/next footers
  image_upload: true           # Upload local images
  resolve_internal_links: true # Convert [[links]]
  flush_before_upload: false   # Delete existing content first

Parsing Order (Priority)

  1. Tables (multi-line, high priority)
  2. Code blocks (multi-line)
  3. Callouts (multi-line, 4 syntaxes)
  4. Images (single line)
  5. Headings (H1-H3)
  6. Task lists (- [ ] / - [x]) - BEFORE unordered lists
  7. Unordered lists (-, *, +)
  8. Ordered lists (1., 2.)
  9. Blockquotes (> text)
  10. Paragraphs (fallback)

NOT Supported

Footnotes ([^1]), Definition lists, HTML inline, Emoji shortcodes (:smile:), H4-H6 headings, Nested blockquotes (>>), Indented code blocks

Patterns to Avoid

Pattern Problem Solution
#### H4 Not supported Use ### H3 or **Bold text**
>12 columns Hard to read Split tables
Callout without > Breaks parsing Every line needs > prefix
Code without language Suboptimal Always specify language

LLM Pre-Upload Checklist

  • Headings max H3 (no H4+)
  • Callouts use valid syntax (prefer GFM)
  • Tables compact (≤ 10 columns recommended)
  • Code blocks have language specified
  • Task lists use - [ ] and - [x]
  • Images use URLs or valid paths
  • Rich text in paragraphs/lists/tables/tasks
  • No HTML inline
  • No unsupported syntax (footnotes, definition lists)
  • julien-ref-doc-production: Use for documentation structure before uploading to Notion