feat(global refactoring): Refactor project architecture and add new features

[Myastr0]

⚠️ Disclaimer

Sorry for reviewers, it's the biggest update on mk-notes due to a folder/file location rework.
Next changes and improvments on this project will be less massive and will be more DDD with the new architecture 🙇‍♂️

Keep Page ID Between Sync

Resolves #67

Summary

This PR introduces the ability to persist Notion page IDs between synchronizations, allowing mk-notes to update existing pages instead of always creating new ones. This is achieved through two new options: --save-id and --force-new.

Key Changes

New Features

• saveId option: When enabled, saves the Notion page ID back to the source markdown file, allowing subsequent syncs to update the same page
• forceNew option: Forces creation of a new page even if an existing page ID is found

Architecture Refactoring

• Reorganized project structure for better maintainability:
  • Moved domain entities to entities/ subdirectories
  • Moved repositories to repositories/ subdirectories
  • Moved infrastructure converters to infrastructure/converters/
  • Moved infrastructure sources to infrastructure/sources/
  • Moved infrastructure destinations to infrastructure/destinations/
  • Moved parsers to infrastructure/parsers/
  • Moved tests closer to their implementation files (__tests__/ folders)

Element Classes Enhancements

• Added optional id property to all Element classes to track Notion block IDs
• Added toContentString() method to all Element classes for serialization back to markdown
• Updated Element constructors to accept id parameter

Source Repository Changes

• Converted File from interface to class with new path property
• Added updateFile() method to SourceRepository interface for writing changes back to source files
• Implemented updateFile() in FileSystemSourceRepository

Other Changes

• Made NotionPage.children mutable (removed readonly)
• Renamed mkNotesInternalId to id in ParseResult for consistency
• Removed deprecated MK_NOTES_INTERNAL_ID_PROPERTY_NAME constant

Documentation Updates

• CLI Commands Guide (docs/content/docs/cli/guides/cli-commands.mdx):

  • Added documentation for --save-id (-s) option with usage examples
  • Added documentation for --force-new (-f) option with usage examples
  • Added new examples: "Syncing with Save ID", "Syncing with Force New", "Combining Force New with Clean and Save ID"
  • Added callouts explaining how incremental updates work

• GitHub Actions Sync Action (docs/content/docs/github-actions/available-actions/2-sync-action.mdx):

  • Added save-id and force-new inputs to the inputs table
  • Added new workflow examples: "Sync with Save ID", "Force New Pages", "Complete Reset with New IDs"
  • Added callout about committing changes when using save-id

• Programmatic Usage Guide (docs/content/docs/cli/guides/programmatic-usage.mdx):

  • Updated SynchronizeOptions interface documentation with new options

• API Documentation (docs/docs/api/):

  • Generated new API reference documentation

---

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?

Usage

CLI

# Sync and save the page ID to source files
mk-notes sync --input ./docs --destination <notion-page-url> --save-id

# Force create new pages even if IDs exist
mk-notes sync --input ./docs --destination <notion-page-url> --force-new

GitHub Action

- uses: mk-notes/mk-notes@v3
  with:
    input: './docs'
    destination: ${{ secrets.NOTION_PAGE_URL }}
    notion-api-key: ${{ secrets.NOTION_API_KEY }}
    save-id: true
    force-new: false

Programmatic

import MkNotes from 'mk-notes';

const mkNotes = new MkNotes({ notionApiKey: '...' });

await mkNotes.synchronizeInputPathToNotionPage({
  inputPath: './docs',
  parentNotionPageId: '...',
  saveId: true,
  forceNew: false,
});

[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