@kirigami/php-prepros 3.1.1 → 3.2.0

package/README.md

@@ -34,6 +34,7 @@ Part of the **Kirigami** project ecosystem.
 
 - [@kirigami/php-prepros](#kirigamiphp-prepros)
 - [Overview](#overview)
+- [What's new in 3.2.0](#whats-new-in-320)
 - [What's new in 3.0.1](#whats-new-in-301)
 - [What's new in 3.0.0](#whats-new-in-300)
 - [What's new in 2.0.0](#whats-new-in-200)
@@ -106,6 +107,15 @@ Part of the **Kirigami** project ecosystem.
 
 ---
 
+## What's new in 3.2.0
+
+- **Markdown pages.** An `_index.md` whose first lines are `@tag value` annotations is a page, like an `_index.php`: its body is rendered as Markdown and wrapped by the layouts. Without that header, or next to an `_index.php`, it stays a data file and is left alone. See [Markdown pages](#markdown-pages).
+- **Inherited annotations.** `@@tag value` sets `tag` on the page and on every page below it; a child's `@tag` overrides it for that page only, a child's `@@tag` overrides it and passes the new value down. Works in PHPDOC blocks and Markdown headers. See [Inherited annotations (`@@`)](#inherited-annotations-).
+- `FS::phpFileInfo()` reads Markdown headers and inherited values, and returns a fresh copy on each call: adding a key to the result no longer leaks into that page's own variables. `FS::getChildren()`, `FS::getBreadcrumb()`, the sitemap and the JSON-LD breadcrumb see `_index.md` pages.
+- The `page_info` hook skips values that aren't strings instead of failing on them.
+
+---
+
 ## What's new in 3.0.1
 
 A registered tag written inside Markdown code is no longer processed. `<markdown>`, `<img asset="...">` or a plugin tag shown in an inline code span (`` `<markdown prose>` ``) or a fenced block (` ``` ` / `~~~`) stays example text: before, a `<markdown>` in a code span paired with the real block's closing tag and broke the rest of the page, and an `<img asset>` in one became an empty image. Indented (four-space) code blocks are not recognized, since `<markdown>` bodies are indented; use a fence there.
@@ -653,7 +663,7 @@ Ordered list of build tasks, run in array order. **Consumed by the `kiri` CLI**,
 
 ## Writing pages
 
-Source pages live in the directory pointed to by `kirigami.root`. The naming convention is straightforward: any file whose name starts with `_` and ends in `.php` is treated as a page source. The leading underscore is stripped in the output filename.
+Source pages live in the directory pointed to by `kirigami.root`. The naming convention is straightforward: any file whose name starts with `_` and ends in `.php` is treated as a page source. The leading underscore is stripped in the output filename. An `_index.md` with an annotation header is a page too (see [Markdown pages](#markdown-pages)).
 
 ```
 src/
@@ -662,6 +672,8 @@ src/
 ├── _index.php          →  src/index.html
 ├── about/
 │   └── _index.php      →  src/about/index.html
+├── notes/
+│   └── _index.md       →  src/notes/index.html
 └── blog/
     ├── _index.php       →  src/blog/index.html
     └── _articles.yaml   (data file, not compiled)
@@ -703,6 +715,57 @@ A value can wrap onto the following **indented** continuation lines:
  */
 ```
 
+### Markdown pages
+
+A page can be pure Markdown: an `_index.md` whose first lines are
+annotations, written like PHPDOC tags without the comment around them.
+
+```markdown
+@title    Hello, world
+@type     post
+@date     2026-09-01
+@abstract The first post.
+
+Some **Markdown** text: the page body.
+```
+
+- The header is the `@tag value` lines at the top of the file (leading blank
+  lines allowed), with the same rules as a PHPDOC block: a value wraps onto
+  indented continuation lines. It ends at the first blank line, or the first
+  flush-left line that isn't a tag, where the body starts.
+- The body goes through `MD::toHtml()` and becomes `$content`, so `@type`,
+  `@indent` and the layouts work as for a PHP page. PHP in the file is never
+  run. `@content other.md` in the header replaces the body.
+- An `_index.md` **without** a header is not a page: it is left alone, as a
+  data file. So is one next to an `_index.php`, which is the page of that
+  folder (it can load the `.md` through an annotation).
+- Only `_index.md` is a page; other `_*.md` files are data files as before.
+
+### Inherited annotations (`@@`)
+
+A tag written with two `@` applies to the page **and every page below it**
+(the pages of its subfolders, and the other pages of its own folder when it is
+an `_index`):
+
+```php
+/**
+ * @title Blog
+ * @@type post            ← every page under blog/ is a post
+ * @@menu _menu.yaml      ← loaded from blog/, wherever the page is
+ */
+```
+
+- A child's `@tag` overrides the inherited value **for that page only**; its
+  own children still get the ancestor's value.
+- A child's `@@tag` overrides it **and passes the new value down**.
+- The nearest ancestor wins. Values come from the page file of each folder
+  above (`_index.php`, else `_index.md`), up to `kirigami.root`.
+- A relative data-file value (`.yaml`/`.yml`/`.json`/`.md`) is resolved
+  against the folder of the page that declared it.
+- In PHPDOC blocks and Markdown headers alike. `FS::getChildren()` and
+  `FS::getBreadcrumb()` entries include inherited values too, so
+  `@@breadcrumb true` turns breadcrumbs on for a whole section.
+
 ### Auto-loading data files
 
 When an annotation value looks like a filename (with a `.yaml`, `.yml`, `.json`, or `.md` extension), it is automatically parsed and injected as a structured variable instead of a plain string.
@@ -1566,18 +1629,20 @@ Filesystem utilities.
 ```php
 FS::dig(string $glob): iterable          // recursive glob, yields file paths
 FS::getRelativePath(string $from, string $to): string
-FS::phpFileInfo(string $file): object|false  // parse PHPDOC annotations
-FS::getChildren(string $backtrace = ''): object[]  // child _index.php pages, ordered by @position
-FS::getBreadcrumb(string $backtrace = ''): object[]  // ancestor _index.php pages, top-most first (opt-in via @breadcrumb)
+FS::phpFileInfo(string $file): object|false  // page annotations (PHPDOC or Markdown header, + inherited @@)
+FS::splitHeader(string $text): array     // Markdown page → [annotations, body, @@ names]
+FS::indexFile(string $dir): ?string      // the folder's _index.php, else _index.md, else null
+FS::getChildren(string $backtrace = ''): object[]  // child _index pages, ordered by @position
+FS::getBreadcrumb(string $backtrace = ''): object[]  // ancestor _index pages, top-most first (opt-in via @breadcrumb)
 FS::rmdir(string $dir, bool $removeSelf = true): bool
 FS::pathJoin(string ...$parts): string   // URL-aware path join with .. resolution
 ```
 
 `FS::dig()` is the workhorse of directory-wide builds — it recursively walks a glob pattern and yields every matching file path.
 
-`FS::phpFileInfo()` parses the first PHPDOC block of a PHP file and returns its `@tag value` pairs as a `stdClass`. This is used internally to resolve page metadata and data-file annotations.
+`FS::phpFileInfo()` parses the first PHPDOC block of a PHP file (or the header of a [Markdown page](#markdown-pages)), merges in the values it [inherits](#inherited-annotations-) from the pages above it, and returns the `@tag value` pairs as a `stdClass`. Each call returns a fresh copy, so adding a key to the result is safe. This is used internally to resolve page metadata and data-file annotations.
 
-`FS::getChildren()` (procedural: `fs_get_children()`) — usable only during a render — scans the folders directly below the calling template, keeps the ones that contain an `_index.php`, and returns one `stdClass` per child: the parsed PHPDOC of that `_index.php` plus a `->file` key with its absolute path. Entries are ordered by `@position` ascending (a page with no `@position` sorts as `999999`), then by folder name (natural, case-insensitive). Handy for building a section index or a navigation menu:
+`FS::getChildren()` (procedural: `fs_get_children()`) — usable only during a render — scans the folders directly below the calling template, keeps the ones that contain an `_index.php` or an `_index.md`, and returns one `stdClass` per child: the parsed PHPDOC of that `_index.php` plus a `->file` key with its absolute path. Entries are ordered by `@position` ascending (a page with no `@position` sorts as `999999`), then by folder name (natural, case-insensitive). Handy for building a section index or a navigation menu:
 
 ```php
 <?php foreach (fs_get_children() as $page): ?>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirigami/php-prepros",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "description": "PHP preprocessor for the Kirigami static site generator. Compile PHP page templates to clean, deployable HTML — with zero server dependency.",
   "keywords": [
     "kirigami",

package/src/libraries/fs.class.php

@@ -52,8 +52,8 @@ class FS
 	 * Lists the immediate child pages of the calling template.
 	 *
 	 * Scans the directories directly below the folder of the file that
-	 * called this function, keeps the ones that hold an `_index.php`, parses
-	 * that file's first PHPDOC block via {@see FS::phpFileInfo()} and returns
+	 * called this function, keeps the ones that hold a page file (see
+	 * {@see FS::indexFile()}), parses its header via {@see FS::phpFileInfo()} and returns
 	 * the pages ordered by `@position` ascending (a missing `@position`
 	 * counts as 999999), then by folder name.
 	 *
@@ -76,10 +76,8 @@ class FS
 
 		$children = [];
 		foreach (glob($dir . '/*', GLOB_ONLYDIR) as $subdir) {
-			$index = $subdir . '/_index.php';
-			if (!is_file($index)) continue;
+			if (!$index = self::indexFile($subdir)) continue;
 			$info = FS::phpFileInfo($index) ?: new stdClass;
-			$info = clone $info;
 			$info->file = realpath($index);
 			$position = (isset($info->position) && is_numeric($info->position)) ? (int) $info->position : 999999;
 			$children[] = ['position' => $position, 'name' => pathinfo($subdir, PATHINFO_BASENAME), 'info' => $info];
@@ -99,7 +97,7 @@ class FS
 	 *
 	 * Starting from the folder *above* the caller's own folder (the current
 	 * page is never part of its own trail), it walks the parent directories
-	 * upward, collecting the `_index.php` of each one via
+	 * upward, collecting the page file (`_index.php` or `_index.md`) of each one via
 	 * {@see FS::phpFileInfo()}. The walk stops at the source root, or at the
 	 * first ancestor `_index.php` that does not carry an active `@breadcrumb`
 	 * tag — that page is a pure separator and is left out of the result.
@@ -138,11 +136,9 @@ class FS
 			$dir = $parent;
 			if (strncmp($dir . '/', $root . '/', strlen($root) + 1) !== 0) break; // above the source root
 
-			$index = $dir . '/_index.php';
-			if (is_file($index)) {
+			if ($index = self::indexFile($dir)) {
 				$info = FS::phpFileInfo($index) ?: new stdClass;
 				if (!self::truthy($info->breadcrumb ?? null)) break;          // separator page: stop, exclude it
-				$info = clone $info;
 				$info->file = realpath($index);
 				$trail[] = $info;
 			}
@@ -168,23 +164,170 @@ class FS
 	}
 
 
+	/**
+	 * The page file of a directory: its `_index.php`, else its `_index.md`,
+	 * else null. A folder holding both is a PHP page, and the `.md` is data.
+	 */
+	public static function indexFile(string $dir): ?string
+	{
+		$dir = rtrim($dir, '\/');
+		foreach (['/_index.php', '/_index.md'] as $name) {
+			if (is_file($dir . $name)) return $dir . $name;
+		}
+		return null;
+	}
+
+
+	/**
+	 * Parses a page's header annotations and returns them as a `stdClass`
+	 * (a fresh copy on each call: callers may add keys without them leaking
+	 * into the page's own variables).
+	 *
+	 * - `.php`: the file's first PHPDOC block ({@see FS::parseDocBlock()}).
+	 * - `.md`:  the `@tag value` lines at the top of the file, up to the
+	 *           first line that is neither a tag nor an indented continuation
+	 *           ({@see FS::splitHeader()}).
+	 *
+	 * Inheritance: an `@@tag value` sets `tag` on the page and on every page
+	 * below it (see {@see FS::inheritedInfo()}). A page's own `@tag`
+	 * overrides an inherited value for that page only; its own `@@tag`
+	 * overrides it and passes the new value down.
+	 */
 	public static function phpFileInfo(string $file): object|bool
 	{
 		static $files = [];
 		if (!$file = realpath($file)) return false;
-		if (!isset($files[$file])) {
-			$tokens = token_get_all(file_get_contents($file));
-			foreach ($tokens as $tok) {
-				if (!is_array($tok)) continue;
-				if ($tok[0] == T_DOC_COMMENT) {
+		$files[$file] ??= (object) array_merge(self::inheritedInfo($file), self::rawInfo($file)[0]);
+		return clone $files[$file];
+	}
+
+
+	/**
+	 * A file's own annotations, as `[all tags, tags passed down (@@)]`.
+	 *
+	 * @return array{0: array<string,string>, 1: array<string,string>}
+	 */
+	private static function rawInfo(string $file): array
+	{
+		static $files = [];
+		if (isset($files[$file])) return $files[$file];
+
+		$inherit = [];
+		if (strtolower(pathinfo($file, PATHINFO_EXTENSION)) === 'md') {
+			[$info, , $inherit] = self::splitHeader(file_get_contents($file));
+		} else {
+			$block = null;
+			foreach (token_get_all(file_get_contents($file)) as $tok) {
+				if (is_array($tok) && $tok[0] == T_DOC_COMMENT) {
 					$block = $tok[1];
 					break;
 				}
 			}
-			if (empty($block)) return new stdClass;
-			$files[$file] = (object) self::parseDocBlock($block);
+			$info = $block ? self::parseDocBlock($block, $inherit) : [];
+		}
+
+		return $files[$file] = [$info, array_intersect_key($info, array_flip($inherit))];
+	}
+
+
+	/**
+	 * The `@@` values a page inherits: those of the page file of every
+	 * folder above it within `kirigami.root`, top-most first, a nearer
+	 * ancestor winning. A non-index page (`_post.php`) also inherits from
+	 * its own folder's `_index`. A relative data-file value
+	 * (`@@menu _menu.yaml`) is rewritten relative to the inheriting page, so
+	 * it still points at the file next to the page that declared it.
+	 *
+	 * @return array<string,string>
+	 */
+	private static function inheritedInfo(string $file): array
+	{
+		if (!isset(PREPROS::$config->root) || !$root = realpath(PREPROS::$config->root)) return [];
+		$root = rtrim(str_replace('\\', '/', $root), '/');
+		$self = str_replace('\\', '/', $file);
+		$dir  = dirname($self);
+		$in   = fn(string $d) => $d === $root || str_starts_with($d, $root . '/');
+		if (!$in($dir)) return [];
+
+		$dirs = [];
+		$isIndex = strtolower(pathinfo($self, PATHINFO_FILENAME)) === '_index';
+		for ($d = $isIndex ? dirname($dir) : $dir; $in($d); $d = dirname($d)) {
+			array_unshift($dirs, $d);
+			if ($d === $root) break;
+		}
+
+		$vars = [];
+		foreach ($dirs as $d) {
+			$index = self::indexFile($d);
+			if (!$index || !$index = realpath($index)) continue;
+			foreach (self::rawInfo($index)[1] as $k => $v) {
+				$ext = strtolower(pathinfo($v, PATHINFO_EXTENSION));
+				if (in_array($ext, ['yaml', 'yml', 'json', 'md'], true) && !STR::is_url($v) && is_file($d . '/' . $v)) {
+					$v = self::relativeTo($dir, realpath($d . '/' . $v));
+				}
+				$vars[$k] = $v;
+			}
 		}
-		return $files[$file];
+		return $vars;
+	}
+
+
+	/** Path of `$file` relative to the directory `$from` (`../x/y.yaml`). */
+	private static function relativeTo(string $from, string $file): string
+	{
+		$from = explode('/', trim(str_replace('\\', '/', $from), '/'));
+		$to   = explode('/', trim(str_replace('\\', '/', $file), '/'));
+		while ($from && $to && $from[0] === $to[0]) {
+			array_shift($from);
+			array_shift($to);
+		}
+		return str_repeat('../', count($from)) . implode('/', $to);
+	}
+
+
+	/**
+	 * Splits a Markdown page into its header annotations and its body.
+	 *
+	 * The header is the `@tag value` lines at the top of the file (leading
+	 * blank lines allowed), with the same rules as a PHPDOC block: a value
+	 * wraps onto following indented lines. It ends at the first blank line
+	 * (consumed) or flush-left line that isn't a tag, where the body starts.
+	 * An `@@tag` is a tag passed down to child pages too. A file with no
+	 * header is all body.
+	 *
+	 * @return array{0: array<string,string>, 1: string, 2: string[]}
+	 *         [annotations, body, names of the `@@` tags]
+	 */
+	public static function splitHeader(string $text): array
+	{
+		$lines   = preg_split('/\r\n|\r|\n/', preg_replace('/^\xEF\xBB\xBF/', '', $text));
+		$info    = [];
+		$inherit = [];
+		$current = null;
+		$count   = count($lines);
+		$i       = 0;
+
+		while ($i < $count && trim($lines[$i]) === '') $i++;
+		if ($i === $count || $lines[$i][0] !== '@') return [[], $text, []];
+
+		for (; $i < $count; $i++) {
+			$line = $lines[$i];
+			if (preg_match('/^@(@?)([A-Za-z0-9_]+)[ \t]*(.*)$/', $line, $m)) {
+				$current = $m[2];
+				$info[$current] = trim($m[3]);
+				$inherit = array_diff($inherit, [$current]);
+				if ($m[1] !== '') $inherit[] = $current;
+			} elseif (str_starts_with($line, '@')) {
+				$current = null;
+			} elseif ($current !== null && trim($line) !== '' && preg_match('/^[ \t]/', $line)) {
+				$info[$current] = trim($info[$current] . ' ' . trim($line));
+			} else {
+				if (trim($line) === '') $i++;                      // the separating blank line
+				break;
+			}
+		}
+
+		return [$info, implode("\n", array_slice($lines, $i)), array_values($inherit)];
 	}
 
 
@@ -198,10 +341,14 @@ class FS
 	 * up to the next `@tag`, a blank line, a flush-left prose line, or the end
 	 * of the block; continuation lines are joined with a single space.
 	 *
-	 * @param  string $block Raw `/** … *&#47;` doc-comment text.
+	 * `@@tag` is a tag like any other, whose name is also added to `$inherit`
+	 * (values passed down to child pages).
+	 *
+	 * @param  string   $block   Raw `/** … *&#47;` doc-comment text.
+	 * @param  string[] $inherit Receives the names of the `@@` tags.
 	 * @return array<string,string>
 	 */
-	private static function parseDocBlock(string $block): array
+	private static function parseDocBlock(string $block, array &$inherit = []): array
 	{
 		$info    = [];
 		$current = null;
@@ -212,9 +359,11 @@ class FS
 			$line = preg_replace('#\s*\*/\s*$#', '', $line);
 			$line = preg_replace('#^[ \t]*\*[ \t]?#', '', $line, 1);
 
-			if (preg_match('/^@([A-Za-z0-9_]+)[ \t]*(.*)$/', $line, $m)) {
-				$current = trim($m[1]);
-				$info[$current] = trim($m[2]);
+			if (preg_match('/^@(@?)([A-Za-z0-9_]+)[ \t]*(.*)$/', $line, $m)) {
+				$current = $m[2];
+				$info[$current] = trim($m[3]);
+				$inherit = array_values(array_diff($inherit, [$current]));
+				if ($m[1] !== '') $inherit[] = $current;
 			} elseif (trim($line) === '') {
 				$current = null;                                   // blank line ends a value
 			} elseif ($current !== null && preg_match('/^[ \t]/', $line)) {

package/src/libraries/ld.class.php

@@ -709,8 +709,8 @@ final class LD
         for ($guard = 0; $guard < 50; $guard++) {
             if (strncmp($dir . '/', $root . '/', strlen($root) + 1) !== 0) break;
 
-            $index = $dir . '/_index.php';
-            if (is_file($index) && (str_replace('\\', '/', @realpath($index) ?: $index)) !== $selfNorm) {
+            $index = FS::indexFile($dir);
+            if ($index && (str_replace('\\', '/', @realpath($index) ?: $index)) !== $selfNorm) {
                 $info = FS::phpFileInfo($index) ?: new stdClass;
                 $fallback = $dir === $root ? self::config()->name : self::humanize(basename($dir));
                 $trail[] = [

package/src/libraries/prepros.class.php

@@ -30,8 +30,10 @@ final class PREPROS
     }
 
 
-    // Only page files beneath the configured source root are publishable.
-    // Check every relative directory, but not the configured root's own name.
+    // Only page files beneath the configured source root are publishable: a
+    // `_*.php`, or an `_index.md` that starts with an `@tag` header, in a
+    // folder that has no `_index.php` (otherwise the `.md` is left alone as
+    // data). Check every relative directory, but not the configured root's own name.
     public static function isPage(string $file): bool
     {
         $file = realpath($file);
@@ -41,7 +43,9 @@ final class PREPROS
         if (!str_starts_with($file, $root)) return false;
         $parts = explode('/', substr($file, strlen($root)));
         $name = array_pop($parts);
-        if (!preg_match('/^_.*\.php$/i', $name)) return false;
+        $isMd = strcasecmp($name, '_index.md') === 0 && !is_file(dirname($file) . '/_index.php')
+            && FS::splitHeader(file_get_contents($file))[0] !== [];
+        if (!$isMd && !preg_match('/^_.*\.php$/i', $name)) return false;
         foreach ($parts as $part) {
             if (str_starts_with($part, '_')) return false;
         }
@@ -66,6 +70,13 @@ final class PREPROS
         $relroot = FS::getRelativePath($dir, self::$root);
         $page = self::processHook('page_info', [$file, FS::phpFileInfo($file)]);
 
+        // A Markdown page is never executed: its body (below the header) is
+        // the page content, unless the header points `@content` elsewhere.
+        $isMd = strtolower(pathinfo($file, PATHINFO_EXTENSION)) === 'md';
+        if ($isMd && !isset($page->content)) {
+            $page->content = MD::toHtml(FS::splitHeader(file_get_contents($file))[1]);
+        }
+
         extract((array)self::$config->data);
         extract((array)$page);
 
@@ -76,7 +87,8 @@ final class PREPROS
         if (self::$config->before) include(realpath(self::$root . self::$config->before));
         $header = self::processHook('post_before', ob_get_clean());
 
-        if(empty($content)) {
+        if ($isMd) $body = (string) $content;
+        elseif(empty($content)) {
             ob_start();
             include($file);
             $body = ob_get_clean();
@@ -130,10 +142,11 @@ final class PREPROS
     {
         $paths = [];
         $root = realpath(self::$root);
-        foreach (FS::dig($root . '/_index.php') as $file) {
+        foreach ([...FS::dig($root . '/_index.php'), ...FS::dig($root . '/_index.md')] as $file) {
             if (!self::isPage($file)) continue;
             $paths[] = str_replace('\\', '/', ltrim(str_replace($root, '', pathinfo(realpath($file), PATHINFO_DIRNAME)), DIRECTORY_SEPARATOR));
         }
+        sort($paths);
         if (empty($paths)) $paths[] = '';
         $dom = new DOMDocument('1.0', 'UTF-8');
         $dom->formatOutput = true;

package/src/libraries/prepros.plugins.php

@@ -51,6 +51,7 @@ PREPROS::registerHook('page_info', function($info) {
 		$file = PREPROS::$file;
 	}
 	foreach($page as $k => $v) {
+		if (!is_string($v)) continue;   // a key a hook or helper added
 		$ext = strtolower(pathinfo($v, PATHINFO_EXTENSION));
 		if(in_array($ext, ['yaml', 'yml', 'json', 'md']) ) {
 			$isUrl = STR::is_url($v);

package/src/prepros.php

@@ -13,7 +13,7 @@ try {
     elseif (!$target = realpath($argv[1])) STD::error("Invalid target.");
     else if (is_dir($target)) {
         $prj = new PREPROS($config);
-        foreach (FS::dig($target . '/*.php', true) as $file) {
+        foreach ([...FS::dig($target . '/*.php'), ...FS::dig($target . '/_index.md')] as $file) {
             if (!PREPROS::isPage($file)) continue;
             PREPROS::render($file);
         }