markedit

name	markedit
description	Provides tools for installing, upgrading, configuring, extending, and troubleshooting MarkEdit, a macOS markdown editor.

Purpose

Help users configure and extend MarkEdit, a free and open-source markdown editor for macOS.

Key Capabilities

• Upgrade the MarkEdit app
• Install, upgrade, and manage MarkEdit extensions
• Submit extensions and themes to the official registry
• Configure MarkEdit settings and supporting files
• Troubleshoot MarkEdit issues
• Answer questions related to MarkEdit

Core Concepts

File Locations

Path	Description
~/Library/Containers/app.cyan.markedit/Data/Documents/scripts/	Extensions directory
~/Library/Containers/app.cyan.markedit/Data/Documents/extensions.json	Installed extension metadata
~/Library/Containers/app.cyan.markedit/Data/Documents/settings.json	Advanced settings
~/Library/Containers/app.cyan.markedit/Data/Documents/editor.css	Custom stylesheets
~/Library/Containers/app.cyan.markedit/Data/Documents/editor.js	Custom JavaScript
~/Library/Containers/app.cyan.markedit/Data/Documents/statistics-rules.json	Custom statistics rules
~/Library/Containers/app.cyan.markedit/Data/Documents/pandoc.yaml	Pandoc defaults
~/Library/Containers/app.cyan.markedit/Data/Documents/debug/	Troubleshooting information

Extension Registry

Use the official registry metadata:

https://raw.githubusercontent.com/MarkEdit-app/extensions/main/index.json

The registry website is useful for browsing. For installation and upgrades, fetch index.json from registry.url in extensions.json, using the official URL above only when that field is absent or null. Do not fall back when extensions.json is malformed. Match the user's request against each entry's name, description, and ID. If multiple entries match, ask the user to choose.

Each entry's latest object provides version, immutable asset url, sha256, and optional minAppVersion. Accept registry schemaVersion values up to 1; stop on a newer version. Require an HTTPS asset URL, a safe kebab-case ID, and a compatible MarkEdit version before installation.

Install the asset as scripts/<id>.js, regardless of the URL filename. Download to a temporary file and verify its SHA-256 against latest.sha256 before replacing anything.

Installed Extension Metadata

extensions.json is structured state shared with MarkEdit. Preserve $schema, registry.url, registry.updateBehavior, unrelated installed records, and the order of the installed array. Validate it against:

https://raw.githubusercontent.com/MarkEdit-app/schemas/main/extensions.json

A registry-installed record contains:

• id: registry ID
• version: installed registry version
• url: downloaded asset URL
• sha256: verified asset hash
• file: <id>.js
• enabled: whether MarkEdit injects the extension
• installDate: ISO 8601 installation timestamp

For a new install, set enabled to true and installDate to the current time. For an upgrade, replace version, url, sha256, and file, while preserving the existing enabled, installDate, and array position.

If extensions.json does not exist, initialize it with the schema URL above, the official registry URL, registry.updateBehavior set to quiet, and an empty installed array.

Common Tasks

Upgrading MarkEdit

MarkEdit supports in-app updates. Prefer the app's updater when the user wants to update interactively.

For an agent-managed upgrade:

1. Retrieve the latest release from GitHub releases
2. Detect the Mac architecture with uname -m
3. Download UpdateArchive-arm64.zip for arm64, or UpdateArchive.zip for Intel
4. Extract the archive to a temporary directory and reject symlinks or an unexpected bundle layout
5. Verify that the staged app matches the installed app's bundle identifier and signing requirement, matches the Mac's architecture, and has the selected release version
6. Back up the installed app, then quit MarkEdit
7. Atomically replace /Applications/MarkEdit.app, restoring the backup if replacement fails
8. Launch MarkEdit and verify the installed version before removing the backup

Use the ZIP release assets instead of DMG installers. Ask before replacing the app if the target is not the standard /Applications/MarkEdit.app or contains local modifications.

Re-Launching MarkEdit

osascript -e 'quit app "MarkEdit"' -e 'delay 1' -e 'launch app "MarkEdit"'

Installing Extensions

1. Fetch and validate the registry index
2. Search it by extension name, description, and ID
3. Confirm the intended entry only when the match is ambiguous
4. Verify latest.minAppVersion against the installed MarkEdit version when present
5. Download latest.url to a temporary file and verify latest.sha256
6. Validate the existing extensions.json, or initialize it with the documented defaults if missing
7. Quit MarkEdit to prevent concurrent writes
8. Atomically install the asset as scripts/<id>.js
9. Upsert the installed record by ID, preserving an existing record's enabled, installDate, and array position, then write the JSON atomically
10. Launch MarkEdit

Back up the destination script and extensions.json before changing them. If either write fails, restore both and report the failure instead of leaving file and metadata state inconsistent.

MarkEdit supports extension deep links, but agent-managed registry installs should complete the download and metadata update directly to avoid user interaction.

For a direct .js URL not present in the registry, require HTTPS, derive a safe kebab-case ID from the filename, verify with the user because it is unreviewed, and install it using the same transaction. Set version to null, pin the downloaded file's SHA-256, and record the source URL.

Listing Extensions

Read extensions.json and correlate its metadata with .js files in the extensions directory. Report available fields such as name, ID, version, source, enabled state, and update information, plus file size and last modification date. Include untracked .js files that have no metadata.

Upgrading Extensions

1. Fetch and validate the latest registry index
2. Match installed records by ID and compare versions numerically
3. Skip records not found in the registry and releases that are older, equal, or incompatible with the installed MarkEdit version
4. Download each newer asset to a temporary file and verify its SHA-256
5. Quit MarkEdit after all requested downloads pass validation
6. Atomically replace each scripts/<id>.js file
7. Update each matching record's version, url, sha256, and file, preserving enabled, installDate, and array position
8. Write extensions.json atomically and launch MarkEdit

Back up all affected scripts and metadata first. Roll back the complete batch if any file or metadata write fails. For legacy markedit-* records without a version, adopt the matching registry entry as an upgrade. Leave unregistered extensions unchanged unless the user provides a newer direct URL.

Uninstalling Extensions

1. Use extensions.json to resolve the extension name or ID to its installed filename
2. Back up the script and extensions.json
3. Quit MarkEdit to prevent concurrent writes
4. Remove the script and its installed record while preserving the order of remaining records
5. Write extensions.json atomically, restoring both backups if either removal fails
6. Launch MarkEdit

Submitting Extensions

Follow the MarkEdit Extension Registry guidelines when submitting an extension or theme:

1. Confirm the injectable .js asset is published at an immutable HTTPS URL, such as a file committed at a release tag
2. Choose a unique kebab-case ID and use the same ID for the registry filename
3. Add extensions/<id>.json for an extension or themes/<id>.json for a theme
4. Set $schema to https://github.com/MarkEdit-app/extensions/raw/refs/heads/main/schemas/extension.schema.json or https://github.com/MarkEdit-app/extensions/raw/refs/heads/main/schemas/theme.schema.json
5. Provide id, name, a one-line description, author, HTTPS homepage, and a non-empty versions array
6. Add the newest release first with semantic version, asset url, and the exact file's sha256
7. Add minAppVersion only when the release requires a newer MarkEdit version, and add concise notes when useful
8. For a theme, also provide colorScheme and colorPatterns; use one palette for light or dark, or two palettes in light-then-dark order for both
9. Validate the entry and open a pull request to MarkEdit-app/extensions

Compute each asset hash from the downloaded bytes:

curl -fsSL -o file "<url>" && shasum -a 256 file

Each theme palette is a comma-separated list of up to six hex colors in this order: background, text, accent, keyword, string, comment.

Keep versions newest-first and retain at most the newest five. Do not add category; the extensions/ or themes/ directory determines it. Do not edit generated index.json or the gallery. The publish workflow supplies addedDate and version date, while featured is maintained by registry curators.

Registry CI validates the schema, ID and filename match, asset reachability, and SHA-256. Review also checks identifiable provenance, integrity, basic quality, and that the extension is not malicious.

Treat the current JSON schemas as authoritative if examples elsewhere in the registry repository are outdated.

Editing Preferences

1. Use the wiki as reference
2. Edit settings.json directly
3. Re-launch MarkEdit

Editing Statistics Rules

1. Use the Custom Statistics Rules documentation as reference
2. Validate statistics-rules.json as a JSON array before and after editing
3. Define each rule with a string title, SF Symbol icon, and regular expression pattern
4. Preserve unrelated rules and remember that rules with zero matches are hidden

Editing Pandoc Defaults

1. Use the Pandoc documentation and defaults-file manual as references
2. Edit pandoc.yaml as YAML while preserving unrelated options and variables
3. Validate the file with Pandoc when it is installed

Troubleshooting

1. Inspect relevant files in the debug/ directory together with the app version, macOS version, and reproduction steps
2. Summarize useful errors and timestamps for the user or a GitHub issue
3. Redact document content, paths, usernames, tokens, and other private data before sharing logs
4. Do not modify or delete debugging files unless the user explicitly asks

Answering Questions

When users ask questions:

1. If it's a task (install, configure, upgrade) → perform the action
2. If it's a customization question → explain editor.css, editor.js, or settings.json
3. If it's a feature question → fetch from wiki and issues
4. If unknown → suggest the wiki or GitHub issues

Examples

• "Upgrade MarkEdit"
• "Install MarkEdit Preview extension"
• "Upgrade MarkEdit Preview"
• "List installed extensions"
• "Remove MarkEdit Preview"
• "Enable autoSaveWhenIdle in MarkEdit"
• "How to customize the editor appearance?"

Error Handling

• If an in-app update fails, use the architecture-appropriate update ZIP from GitHub releases
• If a registry extension cannot be found, show close matches and ask for the extension URL or ID
• If the registry schema is newer than supported, stop and suggest upgrading MarkEdit or this skill
• If minAppVersion is newer than the installed app, stop and report the required version
• If an extension hash does not match, delete the temporary download and do not change installed files or metadata
• If a registry asset download fails (non-200), stop without guessing another URL and report the registry entry
• If extensions.json is malformed or fails schema validation, report the error and do not modify scripts
• If settings.json is malformed, suggest validating JSON syntax
• If statistics-rules.json is malformed, report the JSON error without replacing the user's rules
• If pandoc.yaml is malformed, report the YAML or Pandoc validation error without replacing unrelated settings
• If MarkEdit is not installed, suggest installation methods

Documentation

When answering questions, refer to the MarkEdit Wiki:

Page	URL
Customization	https://github.com/MarkEdit-app/MarkEdit/wiki/Customization
Extensions	https://github.com/MarkEdit-app/MarkEdit/wiki/Extensions
Extension Registry	https://markedit-app.github.io/extensions/
User Manual	https://github.com/MarkEdit-app/MarkEdit/wiki/Manual
Text Processing	https://github.com/MarkEdit-app/MarkEdit/wiki/Text-Processing
Philosophy	https://github.com/MarkEdit-app/MarkEdit/wiki/Philosophy

Search also https://github.com/MarkEdit-app/MarkEdit/issues?q=is%3Aissue%20state%3Aclosed for answered questions or discussed topics.

When answering questions related to development, refer to the MarkEdit API repository too.