Mark
Mark — a tool for syncing your markdown documentation with Atlassian Confluence pages.
This is very useful if you store documentation to your software in a Git repository and don't want to do an extra job of updating Confluence page using a tinymce wysiwyg enterprise core editor which always breaks everything.
Mark does the same but in a different way. Mark reads your markdown file, creates a Confluence page 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.
A document names its page in a few header comments, and the rest is the page:
<!-- Space: DOCS -->
<!-- Parent: Guides -->
<!-- Title: Release process -->
How a release is cut.
mark publish -b https://example.atlassian.net/wiki -u user -p token -f docs/release.mdDocumentation
The reference is split by topic under docs/:
- Page metadata: YAML front matter and header comments,
- Where pages go: parents and folders, parents from the
mark page.
- Formatting: how Markdown becomes Confluence content,
- Attachments and images.
- Links: links to other pages, link checking, and heading
- Includes, macros and templates, with the built-in
- Publishing: publishing to a page by its URL, page
- Exporting a page, or a tree of them, from Confluence back to
- Upgrading to v17: what changed for the command line and
Installation
Homebrew
brew tap kovetskiy/mark
brew install markGo Install
go install github.com/kovetskiy/mark/v17/cmd/mark@latestReleases
Download a release from the Releases page
Docker
docker run --rm -i kovetskiy/mark:latest mark publish <params>Compile and install using docker-compose
Mostly useful when you intend to enhance mark.
# Create the binary
$ docker-compose run markbuilder
"install" the binary
$ cp mark /usr/local/binUsage
mark does one thing per command. mark publish compiles markdown files and
publishes them to Confluence:
mark publish -u user -p token -b https://example.atlassian.net/wiki -f "docs/*/.md"and the experimental mark export writes a Confluence page out as markdown
that publishes back to it; see Exporting a page.
mark doctor checks a setup without changing anything. It logs in with the
global options, says which platform answered, and checks that each space it is
given exists and lets the account create pages and upload attachments. A login
that Confluence answers as the anonymous user fails, since a proxy that drops
the credentials looks like a working login otherwise, and so does an empty
space key, as an unset $SPACE gives. A space without a home page is only a
warning: a page with no Parent header is then published at the top of the
space. When a check fails, it says what to change:
$ mark doctor -b https://example.atlassian.net/wiki -u [email protected] -p "$TOKEN" DOCS
[ok] login: logged in as Jane Doe ([email protected], 5b10ac8d82e05b22cc7d4ef5)
[ok] platform: Confluence Cloud
[ok] space DOCS: "Documentation" is readable
[ok] space DOCS: home page "Documentation Home" (98306)
[ok] space DOCS: can create pages, upload attachments, create blog posts (Type: blogpost)
[warn] space DOCS: cannot delete pages (--on-orphan delete), archive pages (--on-orphan archive), restrict pages (--edit-lock, Restriction headers)
a space administrator grants these under the space's permissionsIt exits with an error when any check fails, and without one when there are
only warnings, so it can also run as the first step of a pipeline. With no
space given it checks --space, from the command line, MARK_SPACE or the
configuration file.
The global options -- the configuration file, how to reach and authenticate
against Confluence, and logging -- belong to every command, and can be given
before or after its name: mark -c ci.toml publish -f doc.md and
mark publish -c ci.toml -f doc.md are the same run. The options of a command
go after its name.
NAME:
mark - A tool for updating Atlassian Confluence pages from markdown.
USAGE:
mark [global options] [command [command options]]
VERSION:
vX.Y.Z
DESCRIPTION:
Mark is a tool to update Atlassian Confluence pages from markdown. Documentation is available here: https://github.com/kovetskiy/mark
COMMANDS:
publish publish markdown files to Confluence
export export a Confluence page, or a tree of them, to markdown (experimental)
page list, move, copy, rename, archive, delete or watch Confluence pages (experimental)
doctor check that mark can reach Confluence, log in, and publish to a space
help, h Shows a list of commands or help for one command
GLOBAL OPTIONS:
--config string, -c string use the specified configuration file. (default: "${HOME}/.config/mark.toml") [$MARK_CONFIG]
--username string, -u string use specified username to authenticate with Confluence. [$MARK_USERNAME]
--password string, -p string use specified token to authenticate with Confluence. Specify - as password to read password from stdin, or your Personal access token. Username is not mandatory if personal access token is provided. For more info please see: https://developer.atlassian.com/server/confluence/confluence-server-rest-api/#authentication. [$MARK_PASSWORD]
--password-command string run the specified command and use the first line of its stdout as the token to authenticate with Confluence. Runs without a shell. Mutually exclusive with password. [$MARK_PASSWORD_COMMAND]
--base-url string, -b string base URL for Confluence. Alternative to the base-url config file key. [$MARK_BASE_URL]
--insecure-skip-tls-verify skip TLS certificate verification (useful for self-signed certificates) [$MARK_INSECURE_SKIP_TLS_VERIFY]
--log-level string set the log level. Possible values: TRACE, DEBUG, INFO, WARNING, ERROR, FATAL. (default: "info") [$MARK_LOG_LEVEL]
--color string display logs in color. Possible values: auto, never. (default: "auto") [$MARK_COLOR]
--help, -h show help
--version, -v print the version
mark publish
NAME:
mark publish - publish markdown files to Confluence
USAGE:
mark publish [options]
DESCRIPTION:
Compile each markdown file --files names into Confluence storage format and create or update the page its metadata names.
OPTIONS:
--files string, -f string use specified markdown file(s) for converting to html. Supports file globbing patterns (needs to be quoted). [$MARK_FILES]
--files-from string read markdown file paths to publish from this file, one per line, or from standard input for "-". Each is taken as written, with no glob meaning, beside any --files pattern. A path that does not exist is not published but still named, so with --partial a deleted file listed there is looked for: pipe in git diff --no-renames --name-only -- '*.md', which names a renamed file under its old path too; every listed file that exists is published, so limit the list to Markdown. [$MARK_FILES_FROM]
--continue-on-error don't exit if an error occurs while processing a file, continue processing remaining files. [$MARK_CONTINUE_ON_ERROR]
--compile-only show resulting HTML and don't update Confluence page content. [$MARK_COMPILE_ONLY]
--dry-run, -n resolve page and ancestry, show resulting HTML and exit. With --changes-only, say which pages would change and show the HTML of only those, and none with --output-format json or github. [$MARK_DRY_RUN]
--edit-lock, -k lock page editing to current user only to prevent accidental manual edits over Confluence Web UI. [$MARK_EDIT_LOCK]
--drop-h1 don't include the first H1 heading in Confluence output. [$MARK_DROP_H1]
--strip-linebreaks, -L remove linebreaks inside of tags, to accommodate non-standard Confluence behavior [$MARK_STRIP_LINEBREAKS]
--title-from-h1 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. Mutually exclusive with --title-from-filename. [$MARK_TITLE_FROM_H1]
--title-from-filename use the filename (without extension) as the Confluence page title if no explicit page title is set in the metadata. Mutually exclusive with --title-from-h1. [$MARK_TITLE_FROM_FILENAME]
--parents-from-path place each page under a page named after every directory between the file pattern's root and the file itself. An index.md or README.md is the page for its own directory rather than a page inside it. A document that names its own Parent is left alone. [$MARK_PARENTS_FROM_PATH]
--parents-from-path-root string the directory --parents-from-path measures from. Taken from the --files pattern when not given, which is everything before its first wildcard. [$MARK_PARENTS_FROM_PATH_ROOT]
--title-append-generated-hash appends a short hash generated from the path of the page (space, parents, and title) to the title [$MARK_TITLE_APPEND_GENERATED_HASH]
--minor-edit don't send notifications while updating Confluence page. [$MARK_MINOR_EDIT]
--watch let the publishing account watch the pages mark creates or edits, as Confluence makes it (default: true, which leaves Confluence's own behaviour alone); --watch=false stops it watching them, though pages it watched already stay watched. [$MARK_WATCH]
--version-message string add a message to the page version, to explain the edit (default: "") [$MARK_VERSION_MESSAGE]
--url string, -l string edit the Confluence page at this URL, as a browser shows it: .../pages/viewpage.action?pageId=ID or .../spaces/KEY/pages/ID/Title. The instance is taken from it too, context path included, unless a base URL is set, which must name the same instance. Without it, each file must name its page with Space and Title metadata headers. [$MARK_PAGE_URL]
--ci run on CI mode. It won't fail if files are not found. [$MARK_CI]
--space string, -s string use specified space key. If the space key is not specified, it must be set in the page metadata. [$MARK_SPACE]
--parents string A list containing the parents of the document separated by parents-delimiter (default: '/'). These will be prepended to the ones defined in the document itself. [$MARK_PARENTS]
--parents-delimiter string The delimiter used for the parents list (default: "/") [$MARK_PARENTS_DELIMITER]
--content-appearance string default content appearance for pages without a Content-Appearance header. Possible values: full-width (Wide), default (Narrow), max (Max). [$MARK_CONTENT_APPEARANCE]
--mermaid-scale float defines the scaling factor for mermaid renderings: the pixels of a png, and the size the page displays an svg at. (default: 1) [$MARK_MERMAID_SCALE]
--mermaid-engine string what mermaid diagrams are drawn by: chrome (the default, a headless browser running mermaid.js) or merman (experimental, a native reimplementation that needs no browser and must be installed separately). (default: "chrome") [$MARK_MERMAID_ENGINE]
--mermaid-output string image a mermaid diagram is published as: png (rasterised, and scaled by --mermaid-scale) or svg (vector and sharp at any zoom, where the instance displays an SVG attachment). (default: "png") [$MARK_MERMAID_OUTPUT]
--mermaid-bundle keep the diagram's own source inside the SVG published for it, in its <desc> element, so the drawing can be edited again from the attachment. Needs --mermaid-output=svg. [$MARK_MERMAID_BUNDLE]
--math-output string image a formula is published as with --features=math: png (rasterised through the same headless Chrome mermaid uses) or svg (vector and sharp at any zoom, where the instance displays an SVG attachment). (default: "png") [$MARK_MATH_OUTPUT]
--math-scale float defines the scaling factor for PNG formula renderings; ignored when --math-output is svg. (default: 2) [$MARK_MATH_SCALE]
--include-path string Path for shared includes, used as a fallback if the include doesn't exist in the current directory. [$MARK_INCLUDE_PATH]
--changes-only Avoids re-uploading pages that haven't changed since the last run. [$MARK_CHANGES_ONLY]
--output-format string how to report what the run did: "url" prints the address of each published page (the default), "json" prints one object describing the whole run, "github" prints GitHub Actions workflow commands so that failures appear against the file that caused them. (default: "url") [$MARK_OUTPUT_FORMAT]
--on-orphan string what to do about a page whose source file is gone: "report" says so and does nothing (the default), "archive" archives the page (Confluence Cloud only), "delete" moves it to the trash. Requires --track-pages. (default: "report") [$MARK_ON_ORPHAN]
--orphan-under string limit --on-orphan, and the reporting it does, to pages below this page or folder, given by title or id. Without it, every tracked page the --files pattern would have published is in scope. [$MARK_ORPHAN_UNDER]
--partial --files and --files-from name only some of the files another run publishes, such as the paths a change touched, deleted ones included: deleted and renamed files are looked for among the tracked files they name, and the rest are left alone. A page keeps the pattern its file was tracked under, so the run publishing them all still notices a deleted file. With --on-orphan archive or delete, name the files with --files-from, or --files as one file: a wildcard is refused. Requires --track-pages. [$MARK_PARTIAL]
--check-links string [ --check-links string ] fail on links that do not resolve. Repeat or comma-separate any of: "internal" (relative links to other files in the repository), "confluence" (ac: links naming a page by title), "external" (requests each URL to see whether it answers), or "all". [$MARK_CHECK_LINKS]
--global-properties string path to a YAML or JSON file of Confluence content properties to set on every page. A Property header or properties front matter in a document wins over the file for that page. [$MARK_GLOBAL_PROPERTIES]
--append-labels add the labels a document asks for without removing any others, so that labels applied in Confluence survive a publish. Without it, a page ends up with exactly the labels its Label headers name. [$MARK_APPEND_LABELS]
--check-links-warn-only report links that do not resolve without failing the run. Only meaningful together with --check-links. [$MARK_CHECK_LINKS_WARN_ONLY]
--links-staged-root string the directory the documents being published were copied or generated into. A relative link that names no file beside a document is then looked for at the same place under --links-source-root, both when it is checked and when it is rewritten. Requires --links-source-root. [$MARK_LINKS_STAGED_ROOT]
--links-source-root string the directory --links-staged-root was made from, where the documents' relative links were written. Requires --links-staged-root. [$MARK_LINKS_SOURCE_ROOT]
--links-source-root-check-only look under --links-source-root only to check a link, not to rewrite it: a link to a file found only there passes --check-links internal and is left as written, rather than pointed at a page read from a file the build has yet to give its headers. Requires --links-source-root. [$MARK_LINKS_SOURCE_ROOT_CHECK_ONLY]
--no-overwrite Leave alone any page that has been edited in Confluence since mark last published it, instead of overwriting the edit. Requires --track-pages, which is where the last published version is remembered. [$MARK_NO_OVERWRITE]
--track-pages Remember which page each file publishes to, so renaming a file or changing its title updates the existing page instead of creating a second one. Stores the mapping in Confluence (a space property on Cloud, a homepage content property on Server/Data Center, or the page --manifest-page names); nothing is written to the repository. [$MARK_TRACK_PAGES]
--manifest-page string keep the --track-pages mapping as content properties of this page, given by title or id, instead of as space properties. Needs only the right to edit that page where a space property needs space administration, and works with a scoped API token. Requires --track-pages. [$MARK_MANIFEST_PAGE]
--manifest-page-optional publish to a space where the --manifest-page page does not exist untracked, with a warning, instead of failing. The mapping is saved if the run publishes that page itself. With --no-overwrite, every existing page in such a space is skipped on every run until the page exists. Requires --manifest-page. [$MARK_MANIFEST_PAGE_OPTIONAL]
--manifest-prefix string name the --track-pages mapping's properties under this prefix, so that two projects publishing into one space keep manifests of their own instead of sharing, and reporting each other's files as gone. Letters, digits, '_', '-' and dots. Requires --track-pages. (default: "mark.manifest") [$MARK_MANIFEST_PREFIX]
--preserve-comments Fetch and preserve inline comments on existing Confluence pages. [$MARK_PRESERVE_COMMENTS]
--d2-output string image a d2 diagram is published as: png (rasterised) or svg (vector and sharp at any zoom, with whatever the diagram references inlined into it, where the instance displays an SVG attachment). (default: "png") [$MARK_D2_OUTPUT]
--d2-bundle-remote let a d2 diagram have mark fetch the URLs it names, and publish what comes back inside the drawing, as svg or png. Off by default, which refuses a diagram that names a URL: the request is made by the document rather than by you, to any address it likes. [$MARK_D2_BUNDLE_REMOTE]
--d2-scale float defines the scaling factor for d2 renderings: the pixels of a png, and the size the page displays an svg at. (default: 1) [$MARK_D2_SCALE]
--features string [ --features string ] Enables optional features, replacing the defaults (mermaid, mention) rather than adding to them; none switches every one off. Current features: d2, date, emoji, frontmatter, inline-link-card, math, mention, mermaid, mkdocsadmonitions, plantuml (default: "mermaid", "mention") [$MARK_FEATURES]
--attach-referenced upload a local file that a link points at, and link to the attachment. Without it the link is published as the path the document wrote, which means nothing once the page is on Confluence. Images are attached either way. [$MARK_ATTACH_REFERENCED]
--image-align string set image alignment (left, center, right). Can be overridden per-file via the Image-Align header. [$MARK_IMAGE_ALIGN]
--page-header string path to a template placed at the top of every page: Markdown if it has a Markdown extension such as .md, storage format otherwise. It is given .Path, .EscapedPath, .Title and .Space. [$MARK_PAGE_HEADER]
--help, -h show help
GLOBAL OPTIONS:
--config string, -c string use the specified configuration file. (default: "${HOME}/.config/mark.toml") [$MARK_CONFIG]
--username string, -u string use specified username to authenticate with Confluence. [$MARK_USERNAME]
--password string, -p string use specified token to authenticate with Confluence. Specify - as password to read password from stdin, or your Personal access token. Username is not mandatory if personal access token is provided. For more info please see: https://developer.atlassian.com/server/confluence/confluence-server-rest-api/#authentication. [$MARK_PASSWORD]
--password-command string run the specified command and use the first line of its stdout as the token to authenticate with Confluence. Runs without a shell. Mutually exclusive with password. [$MARK_PASSWORD_COMMAND]
--base-url string, -b string base URL for Confluence. Alternative to the base-url config file key. [$MARK_BASE_URL]
--insecure-skip-tls-verify skip TLS certificate verification (useful for self-signed certificates) [$MARK_INSECURE_SKIP_TLS_VERIFY]
--log-level string set the log level. Possible values: TRACE, DEBUG, INFO, WARNING, ERROR, FATAL. (default: "info") [$MARK_LOG_LEVEL]
--color string display logs in color. Possible values: auto, never. (default: "auto") [$MARK_COLOR]
mark export
NAME:
mark export - export a Confluence page, or a tree of them, to markdown (experimental)
USAGE:
mark export [options]
DESCRIPTION:
Experimental: the Markdown it writes may change between releases. Write the page --page-id, --url or --space and --title names as markdown, with the metadata headers that publish it back to the same page, and download the attachments it shows or links to.
OPTIONS:
--page-id string export the page or blog post with this id. [$MARK_PAGE_ID]
--url string, -l string export the page at this address, as a browser shows it: /spaces/KEY/pages/ID/... on Cloud, /display/KEY/Title or /pages/viewpage.action?pageId=ID on Server and Data Center, or a short /x/... link on either. Also gives the base URL when --base-url is not set. [$MARK_PAGE_URL]
--space string, -s string the space key --title looks the page up in. [$MARK_SPACE]
--title string, -t string export the page or blog post with this title in --space. [$MARK_TITLE]
--output string, -o string write the Markdown to this file rather than to standard output ("-"). [$MARK_OUTPUT]
--attachments-dir string write the attachments the page shows or links to into this directory. Defaults to the directory of --output, or the working directory; a directory of their own changes their names when the document is published back, since mark names an attachment after its path. [$MARK_ATTACHMENTS_DIR]
--overwrite replace the Markdown file and attachments if they are already there. Without it, the export fails before writing anything. [$MARK_OVERWRITE]
--format string what to write: "mark", a document mark publishes back to the page, or "okf", an Open Knowledge Format concept, and with --recursive a bundle of them, for agents and knowledge catalogs to read. (default: "mark") [$MARK_FORMAT]
--metadata string how a "mark" document spells the metadata that names its page: "comments", HTML comment headers, "frontmatter", YAML front matter, which mark publishes only with the frontmatter feature (--features=mermaid,mention,frontmatter), or "none", the body alone, which cannot be published back by itself: --recursive refuses it on the command line, and sets aside one from MARK_METADATA or the configuration file with a warning. --format okf ignores it. (default: "comments") [$MARK_METADATA]
--no-attachments write the Markdown only, and download no attachments. The document still refers to them where they would have been written. [$MARK_NO_ATTACHMENTS]
--recursive, -r export the pages beneath it too, into the directory --output names: the page to index.md there, and each page beneath it to index.md in a directory of its own named after its title.
--depth int, -d int with --recursive, export this many levels, counting the page itself; 0 is every level. (default: 0)
--relative-links with --recursive, write a link between two exported pages, or a URL of one pasted into a page, as a relative link between their files, which a repository host can follow, rather than as ac:Title or the URL. Published back, such a link becomes a link to the page's address rather than Confluence's own page link.
--help, -h show help
GLOBAL OPTIONS:
--config string, -c string use the specified configuration file. (default: "${HOME}/.config/mark.toml") [$MARK_CONFIG]
--username string, -u string use specified username to authenticate with Confluence. [$MARK_USERNAME]
--password string, -p string use specified token to authenticate with Confluence. Specify - as password to read password from stdin, or your Personal access token. Username is not mandatory if personal access token is provided. For more info please see: https://developer.atlassian.com/server/confluence/confluence-server-rest-api/#authentication. [$MARK_PASSWORD]
--password-command string run the specified command and use the first line of its stdout as the token to authenticate with Confluence. Runs without a shell. Mutually exclusive with password. [$MARK_PASSWORD_COMMAND]
--base-url string, -b string base URL for Confluence. Alternative to the base-url config file key. [$MARK_BASE_URL]
--insecure-skip-tls-verify skip TLS certificate verification (useful for self-signed certificates) [$MARK_INSECURE_SKIP_TLS_VERIFY]
--log-level string set the log level. Possible values: TRACE, DEBUG, INFO, WARNING, ERROR, FATAL. (default: "info") [$MARK_LOG_LEVEL]
--color string display logs in color. Possible values: auto, never. (default: "auto") [$MARK_COLOR]
Upgrading to v17
mark alone no longer publishes: put publish after mark, before the publish
options (mark -c ci.toml publish -f doc.md). Some flags, environment variables
and configuration keys were renamed, unknown configuration keys are refused,
and blockquotes become admonitions only on an explicit marker. Upgrading to
v17 lists every change, for the command line and the Go
library, and what to do about it.
You can store user credentials in the configuration file, which should be
located in a system specific directory (or specified via -c --config ) with the following format (TOML):
username = "your-email"
password = "password-or-api-key-for-confluence-cloud"
Or name a command that prints the token, instead of storing it here:
password-command = "pass show confluence/api-token"
If you are using Confluence Cloud add the /wiki suffix to base-url
base-url = "http://confluence.local"
title-from-h1 = true
drop-h1 = true
image-align = "center"A key is the long name of a flag, without the dashes: every flag that lists an
environment variable in the help, except --config, can be set in the file
too. One file serves every command, so it may hold the keys of publish,
export, doctor and page together, and each command reads the ones it has.
A key that no command has is an error, naming each such key and the one it is
probably a typo of:
unknown key in configuration file "/home/jane/.config/mark.toml": "tittle-from-h1" (did you mean "title-from-h1"?)Before v17 such a key was ignored, so a misspelt setting did nothing and said nothing. A file that still holds one has to lose it, or correct it, to run.
A flag on the command line wins over its environment variable, and that over
the file. Where two settings exclude each other -- --title-from-h1 and
--title-from-filename, or the ways mark export names a page -- one given on
the command line sets aside the other when that came from the environment or
the file. Two from the command line, or two from the environment and the
file, are still an error, which names where each came from.
NOTE: password-command keeps the token out of both the configuration file and the environment.
A password manager or keychain helper supplies it per run.
The command runs without a shell, so the string is split on whitespace and
nothing is expanded: there is no quoting, and a program path or argument
containing a space cannot be written here. Wrap such a helper in a small script
and name the script instead. The command also gets no standard input, so a
helper that prompts on stdin cannot be used -- one that opens the terminal
itself, as pinentry does, is fine.
Only the first line of what the command prints becomes the token, so a helper
that prints a whole entry with the password on top -- pass show does -- needs
no wrapper to trim it.
The command has to fetch the secret rather than contain it. It is handed to the
operating system as written, so anyone who can list processes can read it for as
long as it runs -- which is the exposure password-command exists to avoid, and
writing a token into the command itself puts it straight back.
password and password-command are mutually exclusive, and setting both --
in any combination of flag, environment variable and configuration file -- is an
error rather than a choice mark makes for you. Moving to a command therefore
means taking the password out of the configuration file, not leaving it there
beside the new setting.
A compile resolves the command like any other run, since a relative link is
followed by looking that page up. A helper that cannot produce a token there is
a warning and not an error, because --compile-only has to keep validating
documents on a machine -- a CI image, typically -- that has no password manager
on it.
Scoped API tokens
An Atlassian scoped API token only works through the api.atlassian.com
gateway, so that is what the base URL has to name:
base-url = "https://api.atlassian.com/ex/confluence/<cloud-id>"The gateway checks the token's scopes against the endpoint being called, and the older v1 endpoints check content scopes a scoped token is not usually minted with. Through the gateway mark therefore reads, creates and updates pages with the v2 API, which needs:
| scope | what it is for |
| --- | --- |
| read:space:confluence | resolving a space key and finding its home page |
| read:page:confluence, write:page:confluence | finding, reading, creating and updating pages |
| read:blogpost:confluence, write:blogpost:confluence | the same for blog posts (Type: blogpost) |
| read:attachment:confluence | listing what is attached to a page, and mark export downloading it |
| read:label:confluence | reading the labels a page carries |
| read:content.property:confluence, write:content.property:confluence | the content appearance and emoji title of a page |
| read:page:confluence, write:page:confluence | --track-pages with --manifest-page; without it the mapping is a space property, whose creation a scoped token is refused |
| read:folder:confluence, write:folder:confluence, read:hierarchical-content:confluence | Folder headers: reading and creating folders, and finding one among its parent's direct children |
Uploading attachments, applying Label headers, --preserve-comments,
--on-orphan, --watch=false, page restrictions, mentions, moving a page among its siblings and
finding a folder left at the space root have no v2 endpoint and stay on v1. To use those with a scoped token, grant the
classic scopes (read:confluence-content.all, write:confluence-content,
read:confluence-user) alongside the granular ones.
NOTE: Labels aren't supported when using minor-edit!
NOTE: Attachments are always uploaded as minor edits, whether or not
--minor-edit is set. Watchers are notified about the page update that carries
them, which --minor-edit controls, rather than once more for every file.
NOTE: Confluence makes whoever creates or edits a page watch it, so the
account Mark publishes with is notified of every later change to every page it
touched. --watch=false stops it watching the pages it creates, updates,
moves, labels or attaches files to, parents included, once the run's last write
is done. A page the account already watched before Mark first wrote to it in the
run stays watched, and so does a page an earlier run left watched: Confluence
does not say why an account watches a page. Where the account can be changed,
turning off its own preference to watch what it creates or edits does the same
with no requests, and mark page unwatch --recursive stops it watching pages it
already does.
NOTE: See Preserving Inline Comments for a detailed description of the --preserve-comments flag.
NOTE: The system specific locations are described in here:
--config or MARK_CONFIG names it.
Issues, Bugs & Contributions
I've started the project to solve my own problem and open sourced the solution so anyone who has a problem like me can solve it too. I have no profits/sponsors from these projects which means I don't really prioritize working on this project in my free time. I still check the issues and do code reviews for Pull Requests which means if you encounter a bug in the program, you should not expect me to fix it as soon as possible, but I'll be very glad to merge your own contributions into the project and release the new version.
I try to label all new issues, so it's easy to find a bug or a feature request to fix/implement, if you are willing to help with the project, you can use the following labels to find issues, just make sure to reply in the issue to let everyone know you took the issue:
Contributors ✨
Thanks goes to these wonderful people (emoji key):
