drop attachment:// proto, improve docs

Removed attachment:// proto from docs, back compatibility is saved.
Now using the implementatin of `Attachment:` provided by @csoutherland.

Removed a bunch of swear stuff from docs, oh boy I was so frustrated at
that time.

README.md

@@ -3,40 +3,32 @@
 Mark — tool for syncing your markdown documentation with Atlassian Confluence
 pages.
 
-This is very usable if you store documentation to your orthodox software in git
+This is very useful if you store documentation to your software in a Git
-repository and don't want to do a handjob with updating Confluence page using
+repository and don't want to do an extra job of updating Confluence page using
-fucking tinymce wysiwyg enterprise core editor.
+a tinymce wysiwyg enterprise core editor which always breaks everything.
 
-You can store a user credentials in the configuration file, which should be
+Mark does the same but in a different way. Mark reads your markdown file, creates a Confluence page
-located in ~/.config/mark with following format:
+if it's not found by its name, uploads attachments, translates Markdown into HTML and updates the
+contents of the page via REST API. It's like you don't even need to create sections/pages in your
+Confluence anymore, just use them in your Markdown documentation.
 
-```toml
+Mark uses an extended file format, which, still being valid markdown,
-username = "smith"
+contains several HTML-ish metadata headers, which can be used to locate page inside
-password = "matrixishere"
-base_url = "http://confluence.local"
-```
-
-*NOTE: Cloud Confluence also need to specify /wiki path to the base_url
-parameter.*
-
-Mark understands extended file format, which, still being valid markdown,
-contains several metadata headers, which can be used to locate page inside
 Confluence instance and update it accordingly.
 
-File in extended format should follow specification
+File in the extended format should follow the specification:
 ```markdown
 <!-- Space: <space key> -->
 <!-- Parent: <parent 1> -->
 <!-- Parent: <parent 2> -->
 <!-- Title: <title> -->
-<!-- ExactAttachment: <local path> -->
 <!-- Attachment: <local path> -->
 
 <page contents>
 ```
 
-There can be any number of 'Parent' headers, if mark can't find specified
+There can be any number of `Parent` headers, if Mark can't find specified
-parent by title, it will be created.
+parent by title, Mark creates it.
 
 Also, optional following headers are supported:
 
@@ -55,8 +47,8 @@ to the template relative to current working dir, e.g.:
 <!-- Include: <path> -->
 ```
 
-Templates may accept configuration data in YAML format which immediately
+Templates can accept configuration data in YAML format which immediately
-follows include tag:
+follows the `Include` tag:
 
 ```markdown
 <!-- Include: <path>
@@ -65,29 +57,17 @@ follows include tag:
 
 Mark also supports attachments. The standard way involves declaring an
 `Attachment` along with the other items in the header, then have any links
-start with an `attachment://` pseudo-URL:
+with the same path:
 
 ```markdown
-<!-- Attachment: <path> -->
+<!-- Attachment: <path-to-image> -->
 
 <beginning of page content>
 
-An attached link is [here](attachment://<path>)
+An attached link is [here](<path-to-image>)
 ```
 
-The standard attachment mechanism may not work in some circumstances (e.g.
+**NOTE**: Be careful with `Attachment`! If your path string is a subset of
-keeping content as close to identical as possible between GitHub and
-Confluence), so `ExactAttachment` has been introduced:
-
-```markdown
-<!-- ExactAttachment: <path> -->
-
-<beginning of page content>
-
-An attached link is [here](<path>)
-```
-
-**NOTE**: Be careful with `ExactAttachment`! If your path string is a subset of
 another longer string or referenced in text, you may get undesired behavior.
 
 Mark also supports macro definitions, which are defined as regexps which will
@@ -212,6 +192,16 @@ mark -h | --help
 - `-v | --version`  — Show version.
 - `-h | --help` — Show help screen and call 911.
 
+You can store user credentials in the configuration file, which should be
+located in ~/.config/mark with the following format (TOML):
+
+```toml
+username = "smith"
+password = "matrixishere"
+# If you are using Confluence Cloud add the /wiki suffix to base_url
+base_url = "http://confluence.local"
+```
+
 # Tricks
 
 ## Confluence & Gitlab integration
@@ -250,5 +240,5 @@ Apply:
 
  and declare the following environment variables (secrets)
 * `DOCS_WIKI_USERNAME` — Username for access to Confluence
-* `DOCS_WIKI_PASSWORD` — Password for access to Confluence 
+* `DOCS_WIKI_PASSWORD` — Password for access to Confluence
 * `DOCS_WIKI_BASE_URL` — Base URL of Confluence (cloud users should add /wiki at the end)

main.go

@@ -324,8 +324,13 @@ func main() {
 		}
 	}
 
-	fmt.Printf(
+	log.Infof(
-		"page successfully updated: %s\n",
+		nil,
+		"page successfully updated: %s",
 		creds.BaseURL+target.Links.Full,
 	)
+
+	fmt.Println(
+		creds.BaseURL + target.Links.Full,
+	)
 }

pkg/mark/attachment.go

@@ -186,16 +186,40 @@ func CompileAttachmentLinks(markdown []byte, attaches []Attachment) []byte {
 	})
 
 	for _, replace := range replaces {
-		from := replace
 		to := links[replace]
 
-		log.Debugf(nil, "replacing: %q -> %q", from, to)
+		found := false
+		if bytes.Contains(markdown, []byte("attachment://"+replace)) {
+			from := "attachment://" + replace
 
-		markdown = bytes.ReplaceAll(
+			log.Debugf(nil, "replacing legacy link: %q -> %q", from, to)
-			markdown,
+
-			[]byte(from),
+			markdown = bytes.ReplaceAll(
-			[]byte(to),
+				markdown,
-		)
+				[]byte(from),
+				[]byte(to),
+			)
+
+			found = true
+		}
+
+		if bytes.Contains(markdown, []byte(replace)) {
+			from := replace
+
+			log.Debugf(nil, "replacing link: %q -> %q", from, to)
+
+			markdown = bytes.ReplaceAll(
+				markdown,
+				[]byte(from),
+				[]byte(to),
+			)
+
+			found = true
+		}
+
+		if !found {
+			log.Warningf(nil, "unused attachment: %s", replace)
+		}
 	}
 
 	return markdown

pkg/mark/meta.go

@@ -11,12 +11,11 @@ import (
 )
 
 const (
-	HeaderParent          = `Parent`
+	HeaderParent     = `Parent`
-	HeaderSpace           = `Space`
+	HeaderSpace      = `Space`
-	HeaderTitle           = `Title`
+	HeaderTitle      = `Title`
-	HeaderLayout          = `Layout`
+	HeaderLayout     = `Layout`
-	HeaderAttachment      = `Attachment`
+	HeaderAttachment = `Attachment`
-	HeaderExactAttachment = `ExactAttachment`
 )
 
 type Meta struct {
@@ -89,9 +88,6 @@ func ExtractMeta(data []byte) (*Meta, []byte, error) {
 			meta.Layout = strings.TrimSpace(value)
 
 		case HeaderAttachment:
-			meta.Attachments["attachment://"+value] = value
-
-		case HeaderExactAttachment:
 			meta.Attachments[value] = value
 
 		default: