Skip to content

Publishing

mdai can send the document you are writing to a site of your own — WordPress or Ghost — as a draft or as a published post. It sends your document only when you press Publish, and the document goes straight from your computer to your site, never through mdai.me.

  1. Open Settings → Publishing and click Add.
  2. Give the account a name, choose WordPress or Ghost, and enter the address of your site. It must start with https://; http:// is not allowed.
  3. For WordPress, enter your username and an Application Password. For Ghost, enter the Admin API key; it has the form id:secret.
  4. Click Save.

Enter the address your site really answers on — the one you would type in a browser, for example https://example.com, not the address of its admin page. For Ghost, leave off /ghost. If your site redirects (for instance from www to the bare address), mdai does not follow the redirect and shows “The server responded with error 301” or “302”; use the final address.

The password or key is kept in your computer’s system keychain, never in a file. Edit an account to change it — leave the secret empty to keep the one you already saved. Delete removes the account and its secret from the keychain.

macOS may ask you to allow mdai to use this saved secret. That prompt asks for your Mac’s login password (the one you use to unlock your computer), not the password of your site. Choose Always Allow so it does not ask again.

  1. Open the document and choose File → Publish…
  2. Choose the account and the status: Draft or Publish now.
  3. The dialog shows the site, the title and how many images will be uploaded. Click Publish.

When you open the dialog, mdai asks your site which categories and tags exist and what your account may do. Your document and images are sent only when you press Publish.

For WordPress the dialog lists the site’s categories and tags; for Ghost it lists tags only, because Ghost has no categories. Tick the ones the post should have. You can also type a new tag, and on WordPress a new category; it is created on your site when you publish.

After you publish, mdai writes your choice into the document’s front matter, by name:

categories: [News, Reviews]
tags: [travel]

You can also type these lines yourself before publishing. If the document names a category that does not exist on your site, mdai creates it when you publish, provided your role allows creating categories (see below). If your role does not, mdai tells you and does not publish until you remove that category from the document.

On WordPress the dialog follows the role of the account you chose:

  • Administrator and Editor can create categories and tags and publish straight away.
  • Author can publish, but cannot create a category; it can add a tag.
  • Contributor can only save drafts and cannot upload images. If the document has images, mdai tells you so instead of failing on your site.

Images are uploaded only when they are files inside the vault you have open. An image outside the vault, or any image file when no vault is open, is not uploaded: mdai shows “The image is not inside the open vault.” and asks you to Skip image or Cancel publishing. If you skip, the post is sent without that image and the result tells you how many images were skipped; if you cancel, the post is not sent. To publish a document with its images, open the folder that holds the document and its images as a vault (File → Open Vault…) first. Images embedded in the document itself go out inside the post, and images that are already web addresses (https://) stay links.

When it is done you see “The post was published” or “The post was saved as a draft”, with Open post. For a published post it opens the post on your site. For a WordPress draft it opens the post in the editor of your site (WordPress asks you to sign in first); a draft has no public address.

The images in your document are uploaded to your site together with the post. If an image cannot be uploaded, mdai asks before the post is sent: skip that image and continue, or cancel the publishing.

The post’s title is the title of the document’s front matter; without one, mdai uses the file name. If the front matter has excerpt or slug, they are sent with the post.

The categories and tags you chose are sent (see above). A Mermaid diagram or a formula is not drawn on your site: it arrives as text in a code block.

Links to files on your computer and to other notes in your vault are removed from the post — only their text stays. Web addresses, email links and links within the page stay.

After a document has been published, File → Publish… shows Update post #… and updates that post instead of creating a new one. The status can stay as it is (Keep current status), or you can change it.

mdai remembers the images it has sent to each site, so it does not send them again. If you delete an image from your site’s media library and then update the post, the post may still point to the deleted image; add the image again, or contact support.

If the document was published on a different site than the account you chose, the dialog says so, and publishing makes a new post there.

When a post is created, mdai adds two lines to the top of the document, in its front matter:

published_id: "123"
published_platform: wordpress@your-site.example

For Ghost the second line starts with ghost@.

These two lines are how mdai knows which post to update. Keep them in the document; the categories and tags lines stay with them. If mdai cannot write them (for example, the file was removed while the post was on its way), it tells you the id so you can add them by hand; the post has reached your site either way.

  • Access denied — check the secret and the username.
  • Could not connect to the server — check the address and your connection.
  • The Ghost Admin API key is invalid — the key must be id:secret: 24 characters, a colon, then 64 characters, all hexadecimal.
  • Try again — before you do, look at your site: the post may already have arrived.
  • No secret is stored for this account — enter the password or key again in Settings → Publishing.
  • The system keychain did not accept the secret — your system’s keychain refused to store it. On Linux this needs a running Secret Service such as GNOME Keyring or KWallet.
  • The image is too large — mdai does not upload very large images; skip it or shrink it.

mdai keeps a small log of publishing on your computer. It records the time, the account, what happened and the server’s answer, and never the text of your document, a password or a path. More in the privacy policy.