@kirigami/php-prepros 3.1.1 → 3.2.1

package/package.json

@@ -1,59 +1,59 @@
-{
-  "name": "@kirigami/php-prepros",
-  "version": "3.1.1",
-  "description": "PHP preprocessor for the Kirigami static site generator. Compile PHP page templates to clean, deployable HTML — with zero server dependency.",
-  "keywords": [
-    "kirigami",
-    "php",
-    "preprocessor",
-    "static-site-generator",
-    "ssg",
-    "wasm",
-    "php-wasm",
-    "markdown",
-    "yaml",
-    "github-pages",
-    "pages"
-  ],
-  "license": "GPL-3.0-or-later",
-  "author": "Maxime Larrivée-Roy",
-  "type": "module",
-  "main": "index.js",
-  "types": "index.d.ts",
-  "files": [
-    "index.js",
-    "index.d.ts",
-    "src/",
-    "LICENSE",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=24.0.0",
-    "npm": ">=10.2.3"
-  },
-  "exports": {
-    ".": {
-      "import": "./index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "test": "node --test --test-concurrency=1 \"test/*.test.js\""
-  },
-  "dependencies": {
-    "@kirigami/php-wasm": "8.5.11-1",
-    "@kirigami/struct-walker": "1.0.6",
-    "picomatch": "^4.0.7"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/php-kirigami/kirigami.git"
-  },
-  "homepage": "https://php-kirigami.github.io",
-  "bugs": {
-    "url": "https://github.com/php-kirigami/kirigami/issues"
-  }
-}
+{
+  "name": "@kirigami/php-prepros",
+  "version": "3.2.1",
+  "description": "PHP preprocessor for the Kirigami static site generator. Compile PHP page templates to clean, deployable HTML — with zero server dependency.",
+  "keywords": [
+    "kirigami",
+    "php",
+    "preprocessor",
+    "static-site-generator",
+    "ssg",
+    "wasm",
+    "php-wasm",
+    "markdown",
+    "yaml",
+    "github-pages",
+    "pages"
+  ],
+  "license": "GPL-3.0-or-later",
+  "author": "Maxime Larrivée-Roy",
+  "type": "module",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24.0.0",
+    "npm": ">=10.2.3"
+  },
+  "exports": {
+    ".": {
+      "import": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test --test-concurrency=1 \"test/*.test.js\""
+  },
+  "dependencies": {
+    "@kirigami/php-wasm": "8.5.11-1",
+    "@kirigami/struct-walker": "1.0.6",
+    "picomatch": "^4.0.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/php-kirigami/kirigami.git"
+  },
+  "homepage": "https://php-kirigami.github.io",
+  "bugs": {
+    "url": "https://github.com/php-kirigami/kirigami/issues"
+  }
+}

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/html.class.php

@@ -25,6 +25,7 @@ class HTML
         'code', 'dfn', 'em', 'i', 'img', 'input', 'kbd', 'label', 'map',
         'mark', 'object', 'output', 'q', 's', 'samp', 'select', 'small',
         'span', 'strong', 'sub', 'sup', 'textarea', 'time', 'tt', 'u', 'var',
+        'bdi', 'data', 'del', 'font', 'ins', 'rp', 'rt', 'ruby', 'strike', 'wbr',
     ];
 
     // The HTML namespace URI Lexbor assigns to plain HTML elements (foreign
@@ -188,20 +189,63 @@ class HTML
         }
 
         $inner = '';
-        foreach ($children as $child) {
-            $inner .= static::renderNode($child, $depth + 1);
+        foreach (static::groupInlineRuns($children) as $group) {
+            if (is_array($group)) {
+                // Text and inline elements that follow each other: one line, so
+                // the spaces between them survive ("<b>bold</b>, next").
+                $inner .= str_repeat(' ', ($depth + 1) * self::INDENT) . trim(static::renderInlineNodes($group)) . "\n";
+                continue;
+            }
+            $inner .= static::renderNode($group, $depth + 1);
         }
 
         return "{$pad}<{$tag}{$attrs}>\n{$inner}{$pad}</{$tag}>\n";
     }
 
+    // Splits a block's children into single nodes and runs (arrays) of
+    // consecutive text/inline nodes that contain real text. A run without text
+    // (a row of <a><img></a>, say) stays as separate nodes, one per line.
+    private static function groupInlineRuns(array $children): array
+    {
+        $groups = [];
+        $run    = [];
+        $flush  = static function () use (&$groups, &$run) {
+            $hasText = false;
+            foreach ($run as $node) {
+                if ($node->nodeType === XML_TEXT_NODE && trim($node->nodeValue) !== '') $hasText = true;
+            }
+            if ($hasText) $groups[] = $run;
+            else foreach ($run as $node) $groups[] = $node;
+            $run = [];
+        };
+        foreach ($children as $child) {
+            $isInline = $child->nodeType === XML_TEXT_NODE
+                || ($child->nodeType === XML_ELEMENT_NODE
+                    && static::isInline($child)
+                    && static::hasOnlyInlineChildren($child));
+            if ($isInline) {
+                $run[] = $child;
+            } else {
+                $flush();
+                $groups[] = $child;
+            }
+        }
+        $flush();
+        return $groups;
+    }
+
     // Serializes a node's inline content on a single line, collapsing any run
     // of spaces/tabs/newlines in the source text to a single space (equivalent
     // to HTML's whitespace-collapsing behavior).
     private static function renderInline(Dom\Node $node): string
+    {
+        return static::renderInlineNodes($node->childNodes);
+    }
+
+    private static function renderInlineNodes(iterable $nodes): string
     {
         $out = '';
-        foreach ($node->childNodes as $child) {
+        foreach ($nodes as $child) {
             if ($child->nodeType === XML_TEXT_NODE) {
                 $text = preg_replace('/\s+/', ' ', $child->nodeValue);
                 $out .= htmlspecialchars($text, ENT_QUOTES | ENT_HTML5, 'UTF-8');
@@ -244,6 +288,14 @@ class HTML
         return $elementCount <= 1;
     }
 
+    // A known inline element, or a custom element (its name always has a
+    // hyphen), which browsers lay out inline unless a stylesheet says otherwise.
+    private static function isInline(Dom\Node $node): bool
+    {
+        $name = strtolower($node->nodeName);
+        return in_array($name, self::INLINE, true) || str_contains($name, '-');
+    }
+
     // Checks that every direct descendant is inline (text, inline void, inline elements)
     // The inline elements themselves must not contain block elements
     private static function hasOnlyInlineChildren(Dom\Node $node): bool
@@ -255,7 +307,7 @@ class HTML
             if ($child->nodeType !== XML_ELEMENT_NODE) {
                 return false;
             }
-            if (!in_array(strtolower($child->nodeName), self::INLINE, true)) {
+            if (!static::isInline($child)) {
                 return false;
             }
             // Recursive: the inline element must not contain block elements

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);
         }