Request/feature: clean slate / delete subpages of parent before publish

[petermefrandsen]

If you change the header of a markdown file, I currently end up with two pages in confluence; one old dead page, and the new page maintained by the code.

I might have overlooked some of the many flags, but it would be great if I could set a flag that cleans the targeted parent's subpages, renames the existing confluence page (dif compare) or at least deletes those pages that are not represented in the code.

"With great power comes great responsibility" - I know, but I really need to have the code as my documentation source, and not have doubt about the content in confluence. So this would be a neat feature to me😄

If it is already there, by all means, correct me!

[iamjackg]

Yeah, this is something I've been avoiding on purpose because I wanted to think of an elegant solution. Right now it's possible to rename a page by specifying the page ID for it on the command line, but only when uploading one document at a time. For multiple documents we'd have to keep a mapping of all the existing page IDs, or do what you suggested and wipe all subpages for a parent page. There's still a risk that people will delete pages they don't want to delete, but it can be up to the user.

[petermefrandsen]

Yeah, I completely get you!

In reality, I'd prefer to have a GitHub Action that either compares the current and previous commit git diff HEAD^ HEAD or even better the dry-run of HEAD and HEAD^. This could be done to flag/target pages that potentially should be deleted.

The pages should only be deleted if one of the following:

• The page is identical to the HEAD^ aka no manual edits (so either a comparison of the content or who last modified the page)
• A flag that forces the code is the golden record/source of truth

If none of these conditions is set, you could either break the action or less intrusive create a warning.

This if of course just brainstorming on a feature that'd be nice to have :)

[petermefrandsen]

@iamjackg Considering the complexity of handling individual pages, would you then consider implementing a feature for making a clean deployment?

In other words, the ability to delete all child pages of a parent if specified or the space if no parent?

This is of course very intrusive but would be a great feature if one would like to implement true Docs as Code :)
This feature would need a use with caution comment

Method

The simplest method I have been able to find would be following this article and delete all pages individually:
https://community.atlassian.com/t5/Confluence-questions/How-to-delete-whole-page-tree-with-Rest-API/qaq-p/1273117

This would of course require that you implement the required endpoints into the md2cf confluence rest API implementation.

Tag

This idea could use the --clean or -c tag for such a feature.

The implemented command could look something like this:

Without a parent

md2cf \
  --host $(confluence-host) \
  --token $(confluence-api-key) \
  --space $(confluence-space) \
  --clean \
  ./docs

With a parent

md2cf \
  --host $(confluence-host) \
  --token $(confluence-api-key) \
  --space $(confluence-space) \
  --clean \
  --parent-title "NAME-OF-PARENT" \
  ./docs

[iamjackg]

Hey! Just wanted to let you know that life is very busy these days. If you'd like to see this feature implemented, it would help a lot if you submitted a pull request, even if it's basic.

[petermefrandsen]

@iamjackg I'll have a swing at it, but brace yourself for one that is used to doing .net development 🙂