API Reference Mishka Document v#0.0.1

The documentation extension's Ash domain: its resources (workspaces and their versions, the sections and notes of a version, their drafts, tags, issues and the event log) and the JSON:API routes the admin API serves them under, /v1/master/admin/mishka-document/... for a master and /v1/tenant/admin/mishka-document/... for a site's admin.

A document's own address — where it is read when its admin gives it one, /chelekom/docs — and where each of its pages is read under it.

The text a page's or a note's HTML content reads as, without its markup: what its card, its row and its drafts preview, what its words are counted in, and what its search description is cut from (MishkaDocument.Plugins.PageSeo).

Every read of the document dashboard's widgets (MishkaDocument.Dashboard.Widgets) as the user viewing it, through the resource's own policies.

Registers every mishka_document dashboard widget's own settings with the Settings page through the settings:register mishka_installer hook — so "Documents to show" is documented under the Documents tab (category: "document", group Dashboard widgets) alongside the rest of the extension's settings, instead of hiding inside the dashboard's per-user layout.

Dashboard widget (a dashboard:widgets plugin): open documentation issues — an open-count stat plus the latest few, each with its issue-type badge, filtered to status == :open and read as the viewer through MishkaDocument.Dashboard.Scope: a master sees every site's issues, a site's admin only their own site's, and a viewer without admin:dashboard:document:section none.

Dashboard widget (a dashboard:widgets plugin): the most recently updated workspaces, each with its status badge, one-line description, maintainer, section count, latest version and language — read as the viewer through MishkaDocument.Dashboard.Scope: a master sees every site's workspaces, a site's admin only their own site's, and a viewer without a document area none. Author, section count and latest version come from the resource's own :maintainers_info, :health_metrics calculations and its versions, all loaded on the same read: :master_versions for a master, :tenant_versions for a site's admin. Offered to holders of admin:dashboard:document:section, who read workspaces to reach their sections.

Dashboard widget (a dashboard:widgets plugin): the most recent workspace versions — workspace name, version number, and status badge — read as the viewer through MishkaDocument.Dashboard.Scope with the version's workspace loaded: :master_workspace for a master, :workspace for a site's admin. A master sees every site's versions, a site's admin only their own site's, and a viewer without a document area none. Offered to holders of admin:dashboard:document:workspace.

Dashboard widget (a dashboard:widgets plugin): the full-width dark "Documents" summary panel — a docstats row of totals for workspaces, versions, sections, section drafts, issues, note drafts, and the set of primary languages. Every total is counted as the viewer through MishkaDocument.Dashboard.Scope: a master counts every site's documents, a site's admin only their own site's, and a total whose resource belongs to an area the viewer does not hold is 0. Offered to holders of admin:dashboard:document:workspace.

Generator for MishkaDocument resources.

Dev seeds for MishkaDocument.

Minimal event log for tracking activities in MishkaDocument.

Manages documentation issues and feedback submissions.

Manages comments on documentation issues.

Where this extension's UI kit bundle is, and how to install it.

Manages documentation notes within sections.

Manages draft proposals for note changes within sections.

The rows a documentation page is made of: the document its address names, its published versions, the version a reader is shown and that version's approved pages, the page the address names with its text, and that page's notes.

Tells a site's stylesheet which components its documentation's text draws, which icons it names and which classes it writes, through the runtime:compile:content_components hook MishkaCmsCore.Runtime.Compilers.TailwindCompiler.content_components/1 fires while it builds a site's stylesheet: the names the site's approved pages and notes list in content_components, the icon classes they list in content_icons and the classes they list in content_classes, which MishkaDocument.Resources.Changes.ContentFacts stores when either is written. The kit's doc-section, which draws both with rich_content, then reaches those components (MishkaCmsCore.Runtime.Compilers.CssClosure), the stylesheet carries a rule for each icon, and it is built with each class.

Installs the documentation onto one site, when asked.

Gives a page a live_visit assign: true when the reader reached it by a live navigation, a click on a link of the site or the browser's Back and Forward, and false on a full load.

Tells the site's layout what only a documentation page knows — the languages the document or the page it shows is written in, and the bar under the header — through the runtime:page:frame mishka_installer hook MishkaCmsWeb.RuntimeLive fires in handle_params/3 (MishkaCmsCore.Runtime.SiteLayout is the contract: the map it is handed and what it reads back).

Names the kinds of record the documentation's pages show — a workspace's front page, one of its sections — on the runtime:page:records mishka_installer hook, for a page's "This page shows each" choice (see MishkaCmsCore.Runtime.Seo.record_types/1), each with a few of the site's own to preview a page with. Each is labelled as the Documents admin names it, where its Permissions and SEO Tags are set. MishkaDocument.Plugins.PageSeo answers for the same kinds.

Gives each document and each page of one its own head on the documentation page that serves it, through the runtime:page:seo mishka_installer hook MishkaCmsWeb.RuntimeLive fires in handle_params/3 (see MishkaCmsCore.Runtime.Seo for the map it is handed and what the head builds from it).

Reads the rows a document's front page and each of its pages show, once, through the runtime:page:source mishka_installer hook MishkaCmsWeb.RuntimeLive fires in handle_params/3 before the frame and the head (MishkaCmsCore.Runtime.PageSource is the contract: the map it is handed and where what it reads goes).

A plain mishka_installer plugin: after a documentation page is saved (document:section:after_save — created or updated, a master's twin alike), its share card is looked at in the background and drawn when what it shows changed (MishkaCmsCore.Runtime.ShareCard.refresh/3), so it is ready before the first reader. Only while it is approved and its document active (MishkaDocument.ShareCards.target/1). Registered in MishkaDocument.Application.

A plain mishka_installer plugin: answers MishkaCmsCore.Runtime.ShareCard.targets_event/0 with the documentation's share cards on the site asked, under "mishka_document" — every published document's front page and every page of it, in each language and version a visitor reaches (MishkaDocument.ShareCards.targets/1). Names its producer alone when asked for names, and nothing when another producer is asked (MishkaCmsCore.Runtime.ShareCard.put_targets/3).

Lists a site's published documentation in its /sitemap.xml, through the seo:sitemap:urls mishka_installer hook MishkaCmsCore.Runtime.Compilers.SitemapCompiler fires when it builds the site's sitemap. Its pages are the site's indexable pages holding a capture only their owner can fill; this appends an address for every document and every page of one to its urls. A workspace, version or section written rebuilds its site's sitemap, because those resources list MishkaCmsCore.Runtime.Resources.Notifiers.SitemapRefresh.

Names the words the documentation looks up in a site's translations, through the runtime:translations:used_keys mishka_installer hook (MishkaCmsCore.Runtime.Translations.used_keys/1).

A plain mishka_installer plugin: after a document is saved (document:workspace:after_save — created or updated, a master's twin alike), its share card is looked at in the background and drawn when what it shows changed (MishkaCmsCore.Runtime.ShareCard.refresh/3), so it is ready before the first reader. Only while it is active (MishkaDocument.ShareCards.target/1). Registered in MishkaDocument.Application.

What a site needs before anybody can read its documentation: this extension's live components, three sample pages built out of them, and the "latest documents" block saved as a snippet an author can drop on a home page.

Whether an issue comment was written by a master — a user with no site.

The version numbers of every version cloned from a version, however deep, nearest first — what deleting it deletes with it (MishkaDocument.Resources.Helpers.VersionClones). Read as the reader.

The permissions a section — one page of a document — opens with on its page, in its sitemap entry and wherever else a reader is let in: its own, else those of the nearest parent section that names some, else its document's (the workspace's). What a section names itself always wins over what it would take from above, and a section of a document that names nothing, under parents that name nothing, is public.

When a section — one page of a document — last changed: the newest of its own updated_at, the updated_at of the notes its page shows (approved, not archived) and the time a note was archived, which takes the note off the page. A section with no notes keeps its own.

Calculates unique maintainers count for a section based on EventLog.

Reusable calculation for counting words in a content field.

Calculates unique maintainers for a workspace based on EventLog.

Automatically applies note draft changes when both approvals are granted.

Automatically applies section draft changes when both approvals are granted.

Writes a new version of a document as a copy of one of its versions: every page of the source with its notes and tags, in the source's tree, in one transaction with the new version itself.

The components, the icons and the classes a page's or a note's content names, worked out when it is written — reading either works out nothing

Deleting a version deletes every version cloned from it, however deep, each through the same delete (:destroy, under the version's site) with the same actor — so each is refused, deleted with its pages and notes, logged and broadcast as its own delete would be. The database's source_version_id reference deletes a clone too, for a delete made past the action.

Makes a cloned version independent of the version it was cloned from, in one transaction

Gives a document the two pages its own address is read at, when the address is set — its front page and every page of it (MishkaDocument.Provision.ensure_address!/3) — so an admin who writes /product/docs on the form is answered there without building a page.

Ensures only one version is marked as latest per workspace.

Highlights the code blocks of a page's content — a section's, a note's or a draft of either — with Makeup, once, when it is written.

Sets event metadata for activity log tracking.

Automatically sets section_lineage_id for tracking section versions across workspace versions.

Change module for setting custom version attributes from context.

A draft of an existing record — a page (MishkaDocument.SectionDraft) or a note (MishkaDocument.NoteDraft) — names in its changed_fields which of the record's fields it changes. Applying the draft writes those and no other (MishkaDocument.Resources.Changes.AutoApplySectionDraft, MishkaDocument.Resources.Changes.AutoApplyNoteDraft), so a field its editor did not change is never written over, whatever the record holds by the time the draft is applied.

Extends AshEvents default advisory lock key generator to support nil tenants.

Implements the clear records behavior for event replay.

Ash preparation that tells each event-log row whether it opens a new day in the timeline, and — when it does — how many events that whole day holds. The day heading MishkaCmsCoreWeb.Templates.ActivityTimeline draws is built from both.

The small words, numbers and dates the document resources' tables draw in their cells.

Ash preparation that resolves, for the whole page in ONE query, the site name the master's site badge (event_site column) shows on each event-log row.

Ash preparation that filters event logs by the actor's site_id.

The versions cloned from a version, and from those, however deep: every version whose source_version_id leads back to it. Deleting a version deletes them with it (MishkaDocument.Resources.Changes.DestroyClones); its delete confirmation names them (MishkaDocument.Resources.Calculations.CloneNumbers).

Keeps a public read to the records its reader may open, by the rule the record's page keeps: a record whose lock names permissions opens only for a reader holding one of them (AccessPermissions.match?/3), and never for a visitor who is not signed in. A list leaves out, in its own query, every record the reader may not open, so its pages and its count are of what the reader sees; asking for one of them by itself finds nothing, as an id nothing is stored at does.

Refuses a document's path — its own address, /chelekom/docs — that the site could not answer, or that another document's pages would answer too (MishkaDocument.Address).

Stops a tenant changing an issue comment a master wrote.

Refuses a write onto a record its actor may not open — a bookmark on a locked page of a document, a follow of a locked document — with the message the action gives for a record that is not there, so the refusal tells nothing a reader may not know. Who may open it is what its page asks (MishkaDocument.Resources.Preparations.OpenToActor.opens?/2).

Refuses a record that names, by id, a record of the wrong workspace version.

Refuses a page whose whole address in its version (MishkaDocument.Address) another page of the version already has.

Manages documentation sections within workspace versions.

Manages user bookmarks for documentation sections.

Manages draft proposals for section changes within workspace versions.

Manages the many-to-many relationship between documentation sections and tags.

Tracks unique page views for documentation sections using upsert.

Which share card (MishkaCmsCore.Runtime.ShareCard) a documentation record shows: the kind of record its page shows (MishkaDocument.Plugins.PageRecords) and the captures that name it — what a page of that kind answers for (MishkaDocument.Plugins.PageSeo).

Manages tags for categorizing and organizing documentation sections.

Manages document workspaces in the MishkaDocument plugin.

The two colours a workspace card wears: one for how far along it is, one for what language it is in.

Manages user follows for documentation workspaces.

Which workspaces the admin list shows: one row per document, not one per translation.

Manages workspace versions in the MishkaDocument plugin.

Tracks the lineage and cloning history of workspace versions.

The buttons plugins add to a document's admin screen — the Sections screen of a workspace, /admin/dashboard/document/sections/:workspace_version_id — through the document:workspace:admin_actions mishka_installer event. Each button opens the plugin's own LiveComponent in the screen's modal, one at a time.

Answers /_preview/doc-example/:kind/:id/:index with MishkaDocumentWeb.Live.ExamplePreview: one example of a page of a document, or of one of its notes, drawn alone and live, for the frame of the kit's doc-example Preview dialog.

Admin event-log page at /admin/dashboard/document/event-logs. Mounts the standard MishkaGervaz.Table.Web.Live over MishkaDocument.EventLog, drawn by the shared MishkaCmsCoreWeb.Templates.ActivityTimeline — the same timeline as the unified log at /admin/dashboard/runtime/activity.

The row of figures across the top of the Documents dashboard, each read through Ash as the admin looking at it — a master across every site, a site admin on their own

The comments thread of a single issue, rendered inside the expanded issue card.

One doc-example of a page of a document, or of one of its notes, drawn alone and live: the page the kit's doc-example opens in its Preview dialog's frame, at /_preview/doc-example/<kind>/<id>/<n> (MishkaDocumentWeb.ExamplePreviewController).

Extension routes for MishkaDocument.

The document extension's admin pages and the one sidebar entry that links to them — a "sidebar:menus" plugin (MishkaCmsCore.Sidebar).

The workspaces grid: a hero banner leading a card grid.

The sections list: full-width cards beside a rail of workspace panels.

The issues list: full-width cards, each one able to open a comments panel underneath itself.