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

docs/content/docs/cli/guides/cli-commands.mdx

@@ -62,6 +62,18 @@ mk-notes sync -i <path> -d <notionUrl> -k <notionApiKey>
 
   </Callout>
 
+- `--flat`: Flatten the result page tree, making all pages direct children of the destination instead of maintaining nested folder structures. When enabled, the root node is skipped and all files are created as direct children of the parent page.
+
+  <Callout type="info" title="When to use flat mode">
+
+  Use `--flat` when you want a flat list of pages in Notion rather than a hierarchical structure. This is useful for:
+
+  - Creating a simple list of documents without nested folders
+  - Syncing to databases where you want all items at the same level
+  - Simplifying navigation when folder structure isn't important
+
+  </Callout>
+
 ### Destination Types
 
 Mk Notes supports two types of destinations:
@@ -274,6 +286,46 @@ This command will:
 
 This is useful when you want to completely reset your synchronization and start fresh with new page IDs.
 
+#### Syncing with Flat Structure
+
+```bash
+mk-notes sync \
+  --input ./my-docs \
+  --destination https://notion.so/myworkspace/doc-123456 \
+  --notion-api-key secret_abc123... \
+  --flat
+```
+
+This command will:
+
+1. Read all markdown files in the `./my-docs` directory
+2. **Flatten the structure** - all pages will be created as direct children of the destination page
+3. Skip synchronizing the root node (if your directory has an `index.md`, it will be created as a child page instead of updating the parent)
+4. Display a success message with the Notion page URL when complete
+
+**Example structure:**
+
+Without `--flat`:
+
+```
+Parent Page
+  └── docs/
+      ├── getting-started.md
+      └── guides/
+          └── installation.md
+```
+
+With `--flat`:
+
+```
+Parent Page
+  ├── docs/ (root copy)
+  ├── getting-started.md
+  └── installation.md
+```
+
+All files are now direct children, making navigation simpler.
+
 ## `preview-sync`
 
 The `preview-sync` command lets you preview how your markdown files will be organized in Notion before actually performing the synchronization. This is useful for verifying the structure before making any changes.
@@ -294,6 +346,7 @@ mk-notes preview-sync -i <path> [options]
   - `plainText` (default): Shows a tree-like structure
   - `json`: Outputs the structure in JSON format
 - `-o, --output <output>`: Save the preview to a file instead of displaying it in the terminal
+- `--flat`: Flatten the preview structure, showing how pages will appear when using the `--flat` option in sync. All pages will be displayed as direct children of the root.
 
 ### Examples
 
@@ -341,6 +394,14 @@ mk-notes preview-sync --input ./my-docs --output preview.txt
 mk-notes preview-sync --input ./my-docs/README.md
 ```
 
+5. Preview with flat structure:
+
+```bash
+mk-notes preview-sync --input ./my-docs --flat
+```
+
+This shows how the structure will look when using `--flat` during sync, with all pages as direct children of the root.
+
 ---
 
 ## Single File vs Directory Synchronization

docs/content/docs/cli/guides/database-sync.mdx

@@ -148,6 +148,31 @@ mk-notes sync -i ./docs -d <database-url> -k <api-key> --clean --force-new
 
 </Callout>
 
+### Flat Structure
+
+The `--flat` option flattens the page tree, making all pages direct children of the database instead of maintaining nested folder structures:
+
+```bash
+mk-notes sync \
+  --input ./docs \
+  --destination https://notion.so/myworkspace/database-123456 \
+  --notion-api-key secret_abc123... \
+  --flat
+```
+
+When syncing to databases, `--flat` is particularly useful because:
+
+- All pages appear at the same level in the database
+- Easier to filter and sort all documents uniformly
+- No nested hierarchy to navigate
+- Better for database views where you want all items visible at once
+
+<Callout type="info" title="Database sync with flat">
+
+When using `--flat` with database sync, the root node is skipped and all files become direct database items. This creates a clean, flat list of all your documents in the database, making them easier to manage with database views and filters.
+
+</Callout>
+
 ### Combining Options
 
 You can combine `--save-id` and `--force-new` with `--clean` for different workflows:
@@ -156,8 +181,10 @@ You can combine `--save-id` and `--force-new` with `--clean` for different workf
 | ------------------------------- | ---------------------------------------------------------- |
 | `--save-id`                     | Updates existing pages by ID, saves new IDs to frontmatter |
 | `--force-new`                   | Creates new pages, ignores existing IDs                    |
+| `--flat`                        | Flattens structure, all pages become direct children       |
 | `--clean --save-id`             | Deletes old pages, creates new ones, saves new IDs         |
 | `--clean --force-new --save-id` | Full reset: deletes all, creates new pages, saves new IDs  |
+| `--flat --save-id`              | Flat structure with incremental updates                    |
 
 ---
 

docs/content/docs/github-actions/available-actions/2-sync-action.mdx

@@ -31,15 +31,16 @@ steps:
 
 ## Inputs
 
-| Input            | Description                                                                                                           | Required | Default |
-| ---------------- | --------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
-| `input`          | The path to the markdown file or directory to synchronize                                                             | `true`   | -       |
-| `destination`    | The Notion page or database URL where you want to synchronize your markdown files                                     | `true`   | -       |
-| `notion-api-key` | Your Notion secret token                                                                                              | `true`   | -       |
-| `clean`          | Clean sync mode - removes ALL existing content from the destination before syncing                                    | `false`  | `false` |
-| `lock`           | Lock the Notion page after syncing                                                                                    | `false`  | `false` |
-| `save-id`        | Save Notion page IDs back to the source markdown files' frontmatter, enabling incremental updates on subsequent syncs | `false`  | `false` |
-| `force-new`      | Force creation of new pages, ignoring any existing page IDs in the markdown frontmatter                               | `false`  | `false` |
+| Input            | Description                                                                                                                | Required | Default |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------- | -------- | ------- |
+| `input`          | The path to the markdown file or directory to synchronize                                                                  | `true`   | -       |
+| `destination`    | The Notion page or database URL where you want to synchronize your markdown files                                          | `true`   | -       |
+| `notion-api-key` | Your Notion secret token                                                                                                   | `true`   | -       |
+| `clean`          | Clean sync mode - removes ALL existing content from the destination before syncing                                         | `false`  | `false` |
+| `lock`           | Lock the Notion page after syncing                                                                                         | `false`  | `false` |
+| `save-id`        | Save Notion page IDs back to the source markdown files' frontmatter, enabling incremental updates on subsequent syncs      | `false`  | `false` |
+| `force-new`      | Force creation of new pages, ignoring any existing page IDs in the markdown frontmatter                                    | `false`  | `false` |
+| `flat`           | Flatten the result page tree, making all pages direct children of the destination instead of maintaining nested structures | `false`  | `false` |
 
 ## Destination Types
 
@@ -294,11 +295,47 @@ jobs:
           git push
 ```
 
+### Sync with Flat Structure
+
+Use `flat` to create a flat list of pages instead of maintaining nested folder structures:
+
+```yaml
+name: Flat Sync
+
+on:
+  push:
+    branches: [main]
+    paths: ['docs/**']
+
+jobs:
+  flat-sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Sync with flat structure
+        uses: Myastr0/mk-notes/sync
+        with:
+          input: './docs'
+          destination: ${{ secrets.NOTION_DOCS_PAGE_URL }}
+          notion-api-key: ${{ secrets.NOTION_API_KEY }}
+          flat: 'true'
+```
+
+When `flat: 'true'` is used:
+
+- All pages are created as direct children of the destination page
+- The root node is skipped (if your directory has an `index.md`, it becomes a child page)
+- Folder hierarchy is flattened into a simple list
+- Useful for creating simple document lists or syncing to databases where you want all items at the same level
+
 ## Important Notes
 
 - **For clean sync**: The `clean` option removes ALL existing content from the destination before syncing
 - **For save-id**: Remember to commit the updated markdown files back to your repository
 - **For force-new**: Use with caution as it may create duplicate pages if used without `clean`
+- **For flat**: When using `flat`, the root node is skipped and all files become direct children. This is ideal for simple document lists or database syncs where hierarchy isn't needed
 - Use clean sync only when you're sure you want to replace content
 - Always test with the [preview action](./1-preview-action.mdx) first
 - Make sure your Notion integration has access to the target page or database