Djot #

djot.xhtml #

Produce XHTML-compatible output (self-closing tags like <br /> instead of <br>).

djot:
  xhtml: true

Default: false.

djot.significantNewlines #

When active, soft line breaks in Djot source become <br> tags and block elements like lists can interrupt paragraphs without a blank line.

djot:
  significantNewlines: true

Default: false.

djot.profile #

Select a named converter profile that controls which Djot markup features are allowed during rendering. Profiles are provided by php-collective/djot-php.

djot:
  profile: article

The article profile is a good default for sites with contributor content — it allows all Djot formatting but prevents raw HTML nodes.

Default: null (library default).

Inline [[toc]] directive #

Place [[toc]] as a standalone paragraph in your Djot source to inject a <nav> element at that position:

[[toc]]

## Introduction

## Installation

## Configuration

The injected markup looks like:

<nav class="toc">
  <ul>
    <li><a href="#Introduction">Introduction</a></li>
    <li><a href="#Installation">Installation</a></li>
    <li><a href="#Configuration">Configuration</a></li>
  </ul>
</nav>

Template access #

The $page->toc property holds the collected TocEntry list in document order, indpendently of whether [[toc]] appears in the source. Use it to build sidebar navigation or any custom TOC layout:

<?php foreach ($page->toc as $entry): ?>
<a
  href="#<?= $entry->id ?>"
  class="level-<?= $entry->level ?>"
><?= $entry->text ?></a>
<?php endforeach; ?>

Each TocEntry exposes:

Syntax #

<!--@include: ./partials/intro.dj-->

The path is resolved relative to the file containing the directive. All included paths must stay inside the content root — any path that escapes it (via ../) throws an error at build time.

Line ranges #

Include only a slice of the target file using a {start,end} suffix. Line numbers are 1-based and inclusive.

<!--@include: ./partials/example.dj{3,12}-->
<!--@include: ./partials/example.dj{5,}-->
<!--@include: ./partials/example.dj{,10}-->

• {3,12} — lines 3 through 12
• {5,} — from line 5 to the end of the file
• {,10} — from the start of the file through line 10

Heading anchors #

Include only the section under a specific heading by appending #slug. The section spans from the matched heading to the next heading at the same or higher level.

<!--@include: ./api-reference.dj#basic-usage-->

The slug is derived from the heading text using the same algorithm that generates id attributes: strip #, trim whitespace, replace whitespace sequences with -.

Recursive includes #

Included files are fully expanded — their own <!--@include:--> directives are processed too. Circular includes are detected and cause a build-time error.

Common use case #

Shared code snippets or notes that appear in multiple pages:

## Installation

<!--@include: ../_partials/install-note.dj-->

Run the following command: