[Feature Request] State Change Management

[digital-synapse]

Problem Statement

When a page name is defined with in the header metadata, this title will be used to create / update the page in confluence.

<!-- Title: My Article -->

The problem occurs if ever the title is changed. It seems that mark uses the title as the pageId. mark will assume that this is a new page and create the new page in confluence with the new title, leaving the old page orphaned. This requires some manual cleanup in confluence to delete the orphaned pages after a title change.

Proposal:

Some internal state management is needed. mark should record an internal history log of title changes so that if a title changes mark can correctly update the page instead of creating a new page and orphaning the old one. The history log could be a simple file that is appended each time a publish occurs, or a small sqlite database. Here is an possible format for the history log.

[
  {
    "timestamp" : "2021-12-29 07:22:13",
    "space": "my space",
    "parents": [ "parent page" ],
    "title": "title",
    "md5": "a8bbacece57ccc32e3289b34bce5beb7"
  },
  {
    "timestamp" : "2021-12-30 09:06:56",
    "space": "my space",
    "parents": [ "parent page" ],
    "title": "current title",
    "md5": "ac9359ac35a963dcec0a98f0d693f66c"
  }  
]

Alternatively, If you prefer a smaller state file, just record the previous and the current state rather than the entire history. You will also notice that this records a md5 checksum of the file contents. This can be used to solve a secondary issue which is that mark doesn't currently know when a file change has occurred. Currently (i think), when publishing all pages are update even if there are no changes in the source file. by recording the md5 and comparing it against the current md5 of the markdown file being evaluated, mark can know if it needs to process that file and send an update.

[kovetskiy]

The problem with such solutions is that it can't be used in classic CI scenarios where the state is not shared.

But I understand the problem you are trying to address.

Also, did you know that mark can update a specific page if you pass an URL to a Confluence page? You can use -l <url> and mark will not create a new page with the new title.

Also, what do you think about just having a few titles in the same markdown file? Like as following:

<!-- Title: old title -->
<!-- Title: new title -->

and then mark will try to search for the new title page, if it does not exist, it will look for old title instead, if both don't exist, then mark will create a page with new title.

[digital-synapse]

Yes I see. You make a good point.

Your solution of supporting previous title metadata might be the simplest way to resolve this from an implementation perspective, but it might seem cumbersome from a users point of view to have to track their own title change history? Not sure.

One other possible solution: Store the cache / state file in the confluence space as a hidden file / attachment. That way the state can be shared for classic CI scenarios.

[mtsulek]

I think just adding PageId as metadata would be a very useful thing to have. If I need fixed page in the confluence page tree structure I would just use PageId instead of the title.