MageOS_InlineDocs

In-admin documentation for Magento / Mage-OS: a small marker next to a Stores → Configuration field opens a documentation card explaining what that setting actually does — the field's own label as the heading, a one-line summary, a fuller explanation, and the owning module. The field's config path is a copy-to-clipboard button in the header.

The notes ship inside the module and are served locally. There is no external documentation service, no API token, and no HTTP call on page load — so it is safe to install anywhere and it never depends on anything being reachable.

A marker appears beside any field this module has a note for. Where a field has no native help, the card is the only documentation it gets; where Magento already ships a brief <comment>, the card sits alongside it and goes deeper.

What ships with it

Notes for ~7,400 Mage-OS / Magento core configuration fields — effectively the whole of Stores → Configuration for core. Each carries a one-line summary and an optional fuller usage explanation, with the owning module named in the footer and the config path available as a copy button.

Nine high-traffic sections — Inventory, Sales, Catalog, Customer, Checkout, Payment, Shipping, General and Web — are authored with prose grounded in each field's source classes; the rest carry concise generated notes. The aim is a short, high-signal note per field — what the setting does and what isn't obvious from its label — rather than restating the dropdown options or dumping technical metadata into the popover.

How a field is matched to a note

Magento renders each config field with id="section_group_field", built by Config\Block\System\Config\Form::_generateElementId() as str_replace('/', '_', $path). That transformation is lossy — field names contain underscores — so the path can't be reconstructed from the id with any certainty.

So this module never tries. The page reports the element ids it can see; the module matches them against ids recorded in inline_docs.xml. A lookup, not a guess. (The schema requires each id to be unique, so a lookup never collides.)

Where the notes come from

Every module may ship an etc/inline_docs.xml. They are validated against inline_docs.xsd, merged across all modules, and cached — exactly like Magento's own XML config types. So a third-party module can document its own fields simply by shipping one.

<config xsi:noNamespaceSchemaLocation="urn:magento:module:MageOS_InlineDocs:etc/inline_docs.xsd">
    <field id="cataloginventory_options_show_out_of_stock"
           module="Magento_CatalogInventory"
           section="Inventory"
           path="cataloginventory/options/show_out_of_stock">
        <summary>Shows out-of-stock products in catalog listings and search.</summary>
        <usage><![CDATA[<p>When off, out-of-stock products stay reachable by their direct
            URL but drop out of listings and search. Changing it reindexes the catalog,
            so the storefront keeps the old behaviour until reindexing completes.</p>]]></usage>
    </field>
</config>

Only summary is required; usage is optional, so a field may carry a one-liner or a short card.

• summary — the one-line lead shown bold at the top of the card (also the best candidate for the field's own native <comment>).
• usage — the fuller explanation. May carry a small set of inline HTML (p, ul/ol/li, code, strong, em, a, br), authored in CDATA.
• Attributes: id (the DOM join key, required), module and section (shown in the footer), path (offered as a copy-to-clipboard value in the header), and an optional url for the "Full documentation" link.

The bundled core notes are generated by the companion magento-doc-generator: deterministic extraction from each module's system.xml and the live, merged admin config (so path and module are read, not guessed) → grounded prose → inline_docs.xml.

Install

composer require mage-os-lab/module-inline-docs
bin/magento module:enable MageOS_InlineDocs
bin/magento setup:upgrade
bin/magento cache:flush

Then turn it on: Stores → Configuration → Advanced → Inline Documentation → Enable Inline Documentation → Yes.

Configuration

Stores → Configuration → Advanced → Inline Documentation

Setting	Notes
Enable Inline Documentation	Off by default. Everything is served locally.
Show "Full documentation" Link	Off by default. When on, a note that defines a URL also shows a link through to it.

Architecture

• inline_docs.xml config type — Model/Config/{Reader,Converter,SchemaLocator,Data} parse, validate, merge and cache every module's notes into one id-keyed map.
• Model/InlineDocProvider — resolves a page's element ids to their cards from that map. No network, no token; a miss simply returns nothing.
• Controller/Adminhtml/Inline/Fetch — one request per page returns the cards for the ids on it.
• view/adminhtml/web/js/inline-docs.js — renders the marker and the card (hover to open, click to pin). The usage HTML is rebuilt client-side from a whitelist of inline tags, so a note can never inject script or markup.

Every failure path returns empty and logs. A documentation aid must never break the screen it decorates.

License

MIT — see LICENSE.

Previous Version UI