MarsEdit Configuration

Copy Markdown View Source

MarsEdit is a native macOS blog editor. StaticBlog includes a Micropub endpoint and an XML-RPC shim that together give MarsEdit full read/write access to your blog.

Prerequisites

Start the blog server with a bearer token:

export BLOG_TOKEN=$(openssl rand -hex 32)
mix blog.server

If your project uses a custom token env var (e.g. config :static_blog, :auth_token_env_var, "MY_TOKEN"), export that variable instead.

Note the token value -- you will need it in the MarsEdit configuration below.

Adding the blog in MarsEdit

  1. Open MarsEdit and choose File > New Blog.
  2. Enter the API server URL: http://localhost:4010/
  3. MarsEdit will auto-detect the Micropub endpoint via the <link rel="micropub"> tag on the discovery page.
  4. When prompted, select system type Micropub (or Micro.blog -- both work).
  5. For authentication, enter your token as the API Token or Password (any username is accepted for XML-RPC).

How it works

MarsEdit uses two protocols to talk to StaticBlog:

  • XML-RPC for reading -- listing posts, fetching post content, listing categories. MarsEdit sends microblog.getPosts, metaWeblog.getRecentPosts, metaWeblog.getPost, metaWeblog.getCategories, and related methods.

  • Micropub (JSON/form-encoded) for writing -- creating, updating, and deleting posts. MarsEdit sends standard Micropub requests to /micropub.

Both protocols are served on the same port (default 4010). XML-RPC requests are detected by their Content-Type: text/xml header. XML-RPC uses HTTP Basic authentication (any username, password = token); Micropub uses Authorization: Bearer <token>.

Post editing

  • Content format: MarsEdit receives and sends post content as markdown. This means the source of truth on disk stays as markdown through the entire edit cycle.

  • Categories/tags: MarsEdit's category checklist and free-form tags field both map to the post's :tags list in frontmatter. Changes from either field are merged on save.

  • Draft/published: MarsEdit's post status (Draft / Published) maps to the :status field in frontmatter. Drafts are excluded from the built site but remain visible in MarsEdit's post list.

  • Dates: MarsEdit's published date maps to the :published timestamp in frontmatter. Editing the date in MarsEdit updates the frontmatter but does not rename the file.

Auto-rebuild

Every successful create, update, or delete through the API triggers an automatic rebuild of _site/. The preview server at http://localhost:4000/ reflects changes immediately. Refresh the browser to see updated content.

Troubleshooting

MarsEdit shows "Authentication failed": Verify that the BLOG_TOKEN (or your custom env var) is set and that you entered the same value in MarsEdit. Restart mix blog.server after changing the env var.

Posts appear empty in MarsEdit: MarsEdit should be configured as a Micropub or Micro.blog blog type. Other blog types may not handle the XML-RPC response format correctly.

Changes not appearing in preview: Refresh the browser. The preview server does not support live reload -- it serves static files from _site/.

Post IDs: MarsEdit uses integer post IDs internally. StaticBlog generates these as phash2(slug) hashes. If you manually rename a post file, MarsEdit may treat it as a new post on the next refresh.