kovetskiy/mark v17.0.0

on GitHub

mark v17 is a major release. It makes admonitions predictable, adds an export to the Open Knowledge Format, tightens how settings are read, and gives the Go library a cleaned-up API.

Most command-line users need only a few small changes; see Before you upgrade and the full upgrade guide.

Highlights

Admonitions you can predict

A blockquote now becomes a Confluence info, tip, note or warning box only when you ask for one: a word and a colon at the start of its first line (> Note: …, > **Warning:** …). A quote that merely starts with "Note that …" stays a quote.

Each word now has one colour, whether you write it as > Word:, as a GitHub alert (> [!WORD]) or as an MkDocs admonition (!!! word). The colours follow what GitHub and MkDocs Material show:

MkDocs admonition types now match in any case, so !!! Note works.

Export to the Open Knowledge Format

mark export --format okf writes a page as an OKF concept, and --recursive writes a whole tree as an OKF bundle, with an index.md per directory, relative links between pages and the attachments alongside. mark export --metadata frontmat ter writes the page's metadata as YAML front matter instead of header comments.

One page URL for publish and export

--url (MARK_PAGE_URL, url in the configuration file) names the page for both mark publish and mark export.

Settings that do what you typed

• A typo in the configuration file is reported instead of silently ignored: unknown key in configuration file "mark.toml": "spcae" (did you mean "space"?).
• A setting you type on the command line now wins over a conflicting one from the environment or the configuration file. mark export --page-id 123 works in a CI job that sets MARK_PAGE_URL for publishing, and mark export --space DOCS -r exports the whole space instea
  d of the configured page.

Code blocks that highlight on Data Center

Common language aliases that one Confluence platform doesn't know are mapped to the name it uses, so a fence like ```sh renders highlighted on Data Center instead of failing.

A Go API for v17

For programs built on mark's packages:

• mark.Publisher publishes many files with one browser and one folder cache.
• Settings are options structs instead of long argument lists.
• Every call that reaches Confluence takes a context.Context.
• Enumerated settings have named types.
• mark builds on goldmark v2.
• The Confluence client is an in-repo net/http client with typed errors (errors.Is(err, confluence.ErrNotFound)).
• Nothing is package-level state any more, so two runs in one process no longer share a browser or a folder cache.

Before you upgrade

• Run mark publish, not mark alone: publishing without a command was removed.
• Rename --target-url/MARK_TARGET_URL/target-url to --url/MARK_PAGE_URL/url, export's MARK_URL to MARK_PAGE_URL, and --math-format/MARK_MATH_FORMAT/math-format to --math-output/MARK_MATH_OUTPUT/math-output. A url in a shared configuration
  file now steers publish too.
• Fix unknown keys in your configuration file: they are now an error.
• Check your admonitions. > Note: is now blue (was yellow), > Warning: and > Warn: yellow (was red), MkDocs !!! note blue (was yellow) and !!! warning yellow (was red). Write > Caution: or > Danger: for red. A quote without the colon is no longer a box.
• Content-Appearance accepts only full-width, default and max; anything else, fixed included, is an error.
• attachment://path links are no longer resolved; write the path itself.
• Go programs import github.com/kovetskiy/mark/v17 and follow the upgrade guide.

Fixes

• Exporting a page whose title or attachment names are very long no longer fails with "file name too long".
• A recursive export checks every file it would overwrite before writing anything, instead of failing halfway through a tree.
• An attachment upload that Confluence answers as plain text is no longer reported as failed.
• With the edit lock on, a page is restricted to the user mark logs in as.
• A colon marker inside inline code or an image's alt text no longer turns a quote into a box.
• A failed first file no longer blocks the rest of a single-page (--page-id) run.
• Stopping a run no longer waits for a headless browser that is still starting.
• mark --version names a go install build by its release, and a checkout build by its commit, marked +dirty when the tree had changes.

Full changelog: v16.25.0...v17.0.0

What's Changed

• refactor(markdown)!: remove the legacy compile path by @mrueg in #1149
• build(deps): move to goldmark v2 by @mrueg in #1106
• feat(renderer): map code block language aliases to Confluence's names by @mrueg in #1129
• refactor(confluence)!: replace gopencils with an in-repo HTTP client by @mrueg in #1105
• refactor(stdlib)!: look users up through an interface by @mrueg in #1167
• refactor(util)!: drop publishing with no command by @mrueg in #1161
• refactor(attachment)!: move the upload side to the publishing package by @mrueg in #1168
• refactor(syntax)!: share publish/export Markdown syntax via internal/syntax by @mrueg in #1169
• refactor(metadata)!: move raw-source helpers into internal/mdsource by @mrueg in #1164
• test(util): move the --continue-on-error batch test out of markdown by @mrueg in #1165
• refactor(report)!: move orphan actions to report, tiny links to confluence by @mrueg in #1170
• fix(attachment)!: take an attachment:// link as the URL it is by @mrueg in #1163
• fix(metadata)!: refuse a Content-Appearance mark does not know by @mrueg in #1166
• feat(export)!: write the Open Knowledge Format with --format okf by @mrueg in #1171
• feat(export): write the metadata as YAML front matter with --metadata front-matter by @mrueg in #1174
• fix(export): keep a long title's file name within the file system's limit by @mrueg in #1177
• feat(export): report labels and declared attachments in export.Result by @mrueg in #1173
• fix(export): name an app's edits as a process in OKF, not a person by @mrueg in #1178
• fix(export): keep a title's trailing # in an OKF index heading by @mrueg in #1175
• fix(export): refuse a tree's existing attachments before writing anything by @mrueg in #1176
• refactor!: give each run its own state, and group mark.Config's fields by @mrueg in #1162
• refactor(renderer)!: drop the deprecated admonition aliases by @mrueg in #1179
• refactor(export)!: give the format and metadata options their own types by @mrueg in #1180
• refactor(metadata)!: take ExtractMeta's settings as an options struct by @mrueg in #1181
• build!: move the module to github.com/kovetskiy/mark/v17 by @mrueg in #1068
• refactor(markdown)!: declare package markdown and replace types.MarkConfig with markdown.Options by @mrueg in #1182
• fix(page): LinkChecker race; refactor: one feature list and rendering rules by @mrueg in #1183
• test(markdown): declare features_test.go in package markdown by @mrueg in #1187
• refactor!: split mark.Config into run and publish settings by @mrueg in #1184
• refactor!: take positional flags as option structs, and give the diagram renderers a context by @mrueg in #1185
• feat(cli)!: refuse unknown keys in the configuration file by @mrueg in #1189
• fix(build): describe what the Makefile passes for the version by @mrueg in #1190
• fix(export): write emoji in OKF front matter as themselves by @mrueg in #1192
• refactor!: NewAPI options, drop IsCloud, typed enums by @mrueg in #1186
• refactor(markdown)!: take a context in CompileMarkdown by @mrueg in #1193
• docs: say why in the math renderer and metadata comments by @mrueg in #1194
• fix(cli): list unknown configuration keys on one line by @mrueg in #1199
• perf(renderer): compile the blockquote patterns once by @mrueg in #1195
• fix(export): keep attachment file names within 255 bytes by @mrueg in #1191
• refactor!: share one png/svg output type and name its flags alike by @mrueg in #1196
• feat(cli)!: name the page URL flag --url for publish and export by @mrueg in #1198
• fix(cli): let a setting on the command line set aside a conflicting one from the environment or file by @mrueg in #1202
• feat(renderer)!: turn a blockquote into an admonition only on an explicit marker by @mrueg in #1200
• refactor: share one lazy start between the browser and the mermaid engine, and let Close stop it by @mrueg in #1197
• docs: add an upgrade guide for v17 and drop the README's pre-release note by @mrueg in #1203

Full Changelog: v16.25.0...v17.0.0