Mishka Document - versioned docs with a two-stage review, built with Ash

Mishka Document is the documentation extension for Mishka CMS, written with Elixir, Phoenix LiveView and Ash. A site publishes documentation as documents with several versions, pages that nest to any depth, and notes inside the pages. It is Apache 2.0 and part of the Mishka CMS open-source and free release.

What is in it

  • Versions with the statuses draft, alpha, beta, rc, stable and archived. A version can be cloned from an earlier one, the clone history is recorded, and readers switch versions.
  • A two-stage review. A change to a page or a note is a draft, and it reaches the live record only after both a content review and a technical review approve it.
  • 15 Ash resources, with soft deletes through AshArchival. Documents and pages can be translated, and the translations are linked as one.
  • Issues on a page or note (typo, broken link, suggestion), bookmarks, follows and unique view counts per page.
  • Per page SEO: its own head, TechArticle and breadcrumb JSON-LD, a canonical address, sitemap entries and share cards.
  • A JSON:API for admins and one for readers, described in the CMS’s OpenAPI spec.

How it plugs in

The extension fires named events through Mishka Installer, so a plugin can hook in without touching it. For example, a plugin that adds its own button to a workspace in the admin:

defmodule MyApp.Plugins.WorkspaceButton do
  use MishkaInstaller.Event.Hook, event: "document:workspace:admin_actions"

  def call(state), do: {:reply, state}
end

Other events cover the page head (document:page:seo), extra facts and tabs on a page (document:page:extras) and a cloned version (document:version:cloned). Mishka CMS installs the extension from its wizard, and a host app can add {:mishka_document, "~> 0.0.2"} from Hex.


More: the full write-up on the blog, the Mishka Document documentation and the package on Hex.

Blog post