feat: add flag to append hash to pages to ensure unique titles

issue: kovetskiy#450

README.md

@@ -788,6 +788,7 @@ GLOBAL OPTIONS:
    --drop-h1, --h1_drop                          don't include the first H1 heading in Confluence output. (default: false) [$MARK_H1_DROP]
    --strip-linebreaks, -L                        remove linebreaks inside of tags, to accomodate non-standard Confluence behavior (default: false) [$MARK_STRIP_LINEBREAK]
    --title-from-h1, --h1_title                   extract page title from a leading H1 heading. If no H1 heading on a page exists, then title must be set in the page metadata. (default: false) [$MARK_H1_TITLE]
+   --title-append-generated-hash                 appends a short hash generated from the path of the page (space, parents, and title) to the title (default: false) [$MARK_TITLE_APPEND_GENERATED_HASH]
    --minor-edit                                  don't send notifications while updating Confluence page. (default: false) [$MARK_MINOR_EDIT]
    --version-message value                       add a message to the page version, to explain the edit (default: "") [$MARK_VERSION_MESSAGE]
    --color value                                 display logs in color. Possible values: auto, never. (default: "auto") [$MARK_COLOR]

main.go

@@ -81,6 +81,12 @@ var flags = []cli.Flag{
 		Usage:   "extract page title from a leading H1 heading. If no H1 heading on a page exists, then title must be set in the page metadata.",
 		EnvVars: []string{"MARK_H1_TITLE"},
 	}),
+	altsrc.NewBoolFlag(&cli.BoolFlag{
+		Name:    "title-append-generated-hash",
+		Value:   false,
+		Usage:   "appends a short hash generated from the path of the page (space, parents, and title) to the title",
+		EnvVars: []string{"MARK_TITLE_APPEND_GENERATED_HASH"},
+	}),
 	altsrc.NewBoolFlag(&cli.BoolFlag{
 		Name:    "minor-edit",
 		Value:   false,
@@ -309,7 +315,7 @@ func processFile(
 
 	parents := strings.Split(cCtx.String("parents"), cCtx.String("parents-delimiter"))
 
-	meta, markdown, err := metadata.ExtractMeta(markdown, cCtx.String("space"), cCtx.Bool("title-from-h1"), parents)
+	meta, markdown, err := metadata.ExtractMeta(markdown, cCtx.String("space"), cCtx.Bool("title-from-h1"), parents, cCtx.Bool("title-append-generated-hash"))
 	if err != nil {
 		log.Fatal(err)
 	}
@@ -388,7 +394,7 @@ func processFile(
 		}
 	}
 
-	links, err := page.ResolveRelativeLinks(api, meta, markdown, filepath.Dir(file), cCtx.String("space"), cCtx.Bool("title-from-h1"), parents)
+	links, err := page.ResolveRelativeLinks(api, meta, markdown, filepath.Dir(file), cCtx.String("space"), cCtx.Bool("title-from-h1"), parents, cCtx.Bool("title-append-generated-hash"))
 	if err != nil {
 		log.Fatalf(err, "unable to resolve relative links")
 	}

metadata/metadata.go

@@ -3,6 +3,8 @@ package metadata
 import (
 	"bufio"
 	"bytes"
+	"crypto/sha256"
+	"fmt"
 	"regexp"
 	"strings"
 
@@ -44,7 +46,7 @@ var (
 	reHeaderPatternMacro = regexp.MustCompile(`<!-- Macro: .*`)
 )
 
-func ExtractMeta(data []byte, spaceFromCli string, titleFromH1 bool, parents []string) (*Meta, []byte, error) {
+func ExtractMeta(data []byte, spaceFromCli string, titleFromH1 bool, parents []string, titleAppendGeneratedHash bool) (*Meta, []byte, error) {
 	var (
 		meta   *Meta
 		offset int
@@ -164,6 +166,19 @@ func ExtractMeta(data []byte, spaceFromCli string, titleFromH1 bool, parents []s
 		meta.Parents = append(parents, meta.Parents...)
 	}
 
+	// deterministically generate a hash from the page's parents, space, and title
+	if titleAppendGeneratedHash {
+		path := strings.Join(append(meta.Parents, meta.Space, meta.Title), "/")
+		pathHash := sha256.Sum256([]byte(path))
+		// postfix is an 8-character hexadecimal string representation of the first 4 out of 32 bytes of the hash
+		meta.Title = fmt.Sprintf("%s - %x", meta.Title, pathHash[0:4])
+		log.Debugf(
+			nil,
+			"appended hash to page title: %s",
+			meta.Title,
+		)
+	}
+
 	return meta, data[offset:], nil
 }
 

page/link.go

@@ -34,6 +34,7 @@ func ResolveRelativeLinks(
 	spaceFromCli string,
 	titleFromH1 bool,
 	parents []string,
+	titleAppendGeneratedHash bool,
 ) ([]LinkSubstitution, error) {
 	matches := parseLinks(string(markdown))
 
@@ -46,7 +47,7 @@ func ResolveRelativeLinks(
 			match.filename,
 			match.hash,
 		)
-		resolved, err := resolveLink(api, base, match, spaceFromCli, titleFromH1, parents)
+		resolved, err := resolveLink(api, base, match, spaceFromCli, titleFromH1, parents, titleAppendGeneratedHash)
 		if err != nil {
 			return nil, karma.Format(err, "resolve link: %q", match.full)
 		}
@@ -71,6 +72,7 @@ func resolveLink(
 	spaceFromCli string,
 	titleFromH1 bool,
 	parents []string,
+	titleAppendGeneratedHash bool,
 ) (string, error) {
 	var result string
 
@@ -105,7 +107,7 @@ func resolveLink(
 
 		// This helps to determine if found link points to file that's
 		// not markdown or have mark required metadata
-		linkMeta, _, err := metadata.ExtractMeta(linkContents, spaceFromCli, titleFromH1, parents)
+		linkMeta, _, err := metadata.ExtractMeta(linkContents, spaceFromCli, titleFromH1, parents, titleAppendGeneratedHash)
 		if err != nil {
 			log.Errorf(
 				err,