feat(#70): add option to flat page tree inside a destination

[Myastr0]

Related to #70

Description

This PR adds a new --flat option that allows users to flatten the page tree structure when synchronizing markdown files to Notion. When enabled, all pages become direct children of the destination instead of maintaining nested folder structures, making it particularly useful for database syncs where you want all items at the same level.

Changes

Core Features

• Added flatten() method to TreeNode: Recursively flattens all children, excluding the root node itself
• Added flatten() method to SiteMap: Returns a new SiteMap instance with the tree flattened under the root node, including a root copy as the first child
• Updated SynchronizeMarkdownToNotion feature:
  • Added flatten option to SynchronizeOptions interface
  • When flatten is true, the root node is skipped during synchronization
  • All flattened pages are created as direct children of the parent page/database
  • Refactored root node synchronization logic to handle both page and database destinations separately
• Updated PreviewSynchronization feature: Added flatten option to preview how the structure will look when flattened

CLI Commands

• sync command: Added --flat flag to flatten the result page tree
• preview-sync command: Added --flat flag to preview flattened structure

GitHub Actions

• Sync action: Added flat input parameter to support flattening in CI/CD workflows

Documentation

• Updated CLI commands documentation with examples and use cases for the --flat option
• Updated database sync guide with flat structure section
• Updated GitHub Actions documentation with flat sync examples
• Added callouts explaining when and why to use flat mode

Tests

• Added comprehensive unit tests for TreeNode.flatten() method
• Added comprehensive unit tests for SiteMap.flatten() method
• Added tests for PreviewSynchronization with flatten option
• Added tests for MkNotes class with flatten option
• Updated existing tests to account for the new flatten parameter

Use Cases

The --flat option is particularly useful for:

1. Database syncs: When syncing to Notion databases, flat structure ensures all documents appear at the same level, making them easier to filter, sort, and manage with database views
2. Simple document lists: Creating a flat list of documents without nested folder structures
3. Simplified navigation: When folder hierarchy isn't important and you want all pages visible at once

Example

Without --flat:

Parent Page
  └── docs/
      ├── getting-started.md
      └── guides/
          └── installation.md

With --flat:

Parent Page
  ├── docs/ (root copy)
  ├── getting-started.md
  └── installation.md

Testing

• All existing tests pass
• New tests added for flatten functionality
• Tests cover edge cases (empty trees, nested structures, root node handling)
• Manual testing performed for both CLI and GitHub Actions

Checklist

All Submissions:

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?

New Feature Submissions:

1. Does your submission pass tests?
2. Have you lint your code locally before submission?

Changes to Core Features:

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your core changes, as applicable?
• Have you successfully run tests with your changes locally?

[Myastr0]

👋 Hi, Myastr0! Thanks for opening a PR. We will review it soon.
If you have any questions, feel free to join the #need-help channel on the Discord server