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

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

13. Internal Links

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:

MIXED (Recommended for docs)

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)

Tables (multi-line, high priority)
Code blocks (multi-line)
Callouts (multi-line, 4 syntaxes)
Images (single line)
Headings (H1-H3)
Task lists (- [ ] / - [x]) - BEFORE unordered lists
Unordered lists (-, *, +)
Ordered lists (1., 2.)
Blockquotes (> text)
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)

Related Skills

julien-ref-doc-production: Use for documentation structure before uploading to Notion

julien-ref-notion-markdown