Docly Developers
Function Updated 22 Oct 2026

Master directive(file)

Uses another file as master page (layout) for this page. The page's own code runs first; then the master file is rendered and the page is merged into it. Elements in the page carry an xdt:Transform attribute that says what to do with them.

Supported actions (case-insensitive):

  • Replace — replaces the matching element in the master.
  • Insert — adds the whole element as the last child of the matching parent in the master (the parent is found from the element's own position, for example html > head). Create is an alias for Insert.
  • Append — Docly-specific: adds the element's inner content as the last children of the matching element. This is not the same as Insert.
  • InsertBefore(selector) / InsertAfter(selector) — inserts the element as a sibling before or after the element the selector matches, for example InsertAfter(div[id=menu]).
  • SetAttributes — copies the element's attributes to the matching element.
  • Remove / RemoveAll — removes the first / all matching elements.
  • RemoveAttributes(attr1,attr2) — removes the listed attributes from the matching element.

The matching element in the master is found with xdt:Locator="Match(attr)" if present, otherwise by the element's id, otherwise by its tag path from <html> downwards.

Most mistakes are silent in the rendered page: a transform whose target is not found is skipped, and an unknown <!--#…--> directive is removed. They are reported as compile errors when the file is saved and by the compile-error scan. Three mistakes write an XDT ERROR text into the page: an unknown action name (when the target exists), InsertBefore/InsertAfter without a selector, and Insert/Create when the parent path is not found in the master. A missing master file writes MASTER ERROR, FILE NOT FOUND (…).

A master file may itself use <!--#master-->, so layouts can be nested. Directives are not processed in #/API files.

A master page is shared by pages in different sub-folders, so reference assets (CSS, JS, images) with absolute paths starting with "/", for example "/css/style.css". They then resolve the same way from every page.

Parameters

filestringrequired

Path to the file in double quotes, resolved from the site root — a leading / is optional, so "Header.hash" and "/Header.hash" are the same file. Paths are not relative to the current page's folder. A path starting with #/ falls back to the site template's file when the site has no own copy.

Returns

The page merged into the master page.

Example

Mixed HTML (or any text file) with inline JavaScript between hash signs.
<!--#master file="/master.hash"-->
<html>
    <head>
        <title xdt:Transform="Replace">My Page Title</title>
        <link href="/css/custom.css" rel="stylesheet" xdt:Transform="Insert" />
        <script src="/js/page.js" xdt:Transform="Insert"></script>
    </head>
    <body>
        <div id="page-content" xdt:Transform="Replace">
            <h1>Welcome</h1>
            <p>This is my page content.</p>
        </div>
    </body>
</html>