Vague concepts of hierarchy in synchronization

[basiekjusz]

I have a problem with understanding what's the hierarchy of documents when synchronizing, depending on different scenarios.

Consider the following local folder structure, similar to the one from examples in docs:

test
├── api-reference.md
├── getting-started
│   ├── configuration.md
│   ├── index.md
│   └── installation.md
├── guides
│   ├── advanced-features
│   │   └── customization.md
│   └── basic-usage.md
└── index.md

Here the preview command results with:

mk-notes preview-sync --input test
├─  (Your parent Notion Page)
│   ├─ test/api-reference.md (api-reference.md)
│   ├─ test/guides/advanced-features/customization.md (guides)
│   │   ├─ test/guides/basic-usage.md (basic-usage.md)
│   ├─ test/index.md (index.md)
│   ├─ test/getting-started/configuration.md (configuration.md)
│   ├─ test/getting-started/installation.md (installation.md)

Consider running the following simple command for the synchronization:

mk-notes sync \
  --input test \
  --destination $NOTION_DESTINATION_URL \
  --notion-api-key $NOTION_API_KEY

Page synchronization

Here the NOTION_DESTINATION_URL points to a single Notion page.

The preview command run does result with something that is quite similar to the final result in Notion, however it doesn't really state which page is going to be the root one.

When synchronizing to a single root page, the root is replaced with the content of the getting-started/index.md, with the following children linked at the end:

├── getting-started (getting-started/index.md)
│   ├── api-reference (api-reference.md)
│   ├── customization (guides/advanced-features/customization.md)
│   │   └── basic-usage (guides/basic-usage.md)
│   ├── index (index.md)
│   ├── configuration (getting-started/configuration.md)
│   └── installation (getting-started/installation.md)

This is doesn't really follow any of the schema that's considered on the docs page, as none of the files become subsections, according to this: https://mk-notes.io/docs/cli/guides/architecture/#example-structure. The pages on similar nesting level, doesn't really end up keeping this hierarchy.
Also, is quite counterintuitive, as the page that is nested deeper can become the root one in the hierarchy (for example getting-started/index.md ignoring ./index.md and guides/advanced-features/customization.md ignoring guides/basic-usage.md).

Database synchronization

Here the NOTION_DESTINATION_URL points to a database. I keep the same command for synchronization (I'm not using --flat flag).

The structure looks different here:

├── getting-started (getting-started/index.md)
├── api-reference (api-reference.md)
├── customization (guides/advanced-features/customization.md)
│   └── basic-usage (guides/basic-usage.md)
├── index (index.md)
├── configuration (getting-started/configuration.md)
└── installation (getting-started/installation.md)

There's also difference in how the documents are linked to each other. While on single page the root page (getting-started/index.md) gets the children linked to it, here the only page that gets link to its child is the customization.md. For some reason, the hierarchy from single page isn't kept here.

---

Summary

After testing both Page and Database synchronization, the current behavior presents several critical inconsistencies:

• Hierarchy Inversion: The tool does not respect the filesystem hierarchy. Deeply nested files (like getting-started/index.md) are being promoted to root pages, while top-level files (like ./index.md) are treated as children.
• Loss of Directory Structure: Folders are not consistently converted into subsections or parent pages. Instead, the structure is partially flattened or linked arbitrarily and doesn't keep the folder organization structure.
• Mode Divergence: There is a lack of parity between how "Page" sync and "Database" sync handle parent-child relationships, even when using identical source files.

The current synchronization logic feels non-deterministic and makes it difficult to maintain a reliable documentation structure in Notion. The primary value of mk-notes should be the "Source of Truth" relationship with the local filesystem, but currently, the tool reorganizes content in a way that breaks logical navigation.

Possible solution

In my opinion (and according to what other tools like mkdocs do) the most consistent and intuitive mapping logic would be:

1. Folders represent Parent Pages.
2. Files represent Child Pages.
3. The "Index" Resolution:
   a. If a folder contains index.md, the content of the Notion Parent Page is this file + the list of children pages is appended to the end of the file.
   b. If a folder does not contain index.md, the Notion Parent Page is created as a container (titled after the folder) and contains it's list of content (links to children pages)

So for the example we achieve the following structure:

(Notion Root Page) [Content: index.md]
  ├── api-reference [Content: api-reference.md]
  ├── getting-started [Content: getting-started/index.md]
  │     ├── configuration [Content: getting-started/configuration.md]
  │     └── installation [Content: getting-started/installation.md]
  └── guides [Content: links to it's children]
        ├── basic-usage [Content: guides/basic-usage.md]
        └── advanced-features [Content: link to it's children]
              └── customization [Content: guides/advanced-features/customization.md]

Thanks to that, we achieve pretty straightforward hierarchy that is easy to understand and deterministic.