diff --git a/config/common/di/content-pipeline.php b/config/common/di/content-pipeline.php
index a6c930f..0a1ca6d 100644
--- a/config/common/di/content-pipeline.php
+++ b/config/common/di/content-pipeline.php
@@ -50,6 +50,7 @@
'class' => ContentProcessorPipeline::class,
'__construct()' => [
Reference::to(MarkdownProcessor::class),
+ Reference::to(TagLinkProcessor::class),
],
],
BuildCommand::class => [
diff --git a/docs/deployment.md b/docs/deployment.md
index 5df0f74..18906d2 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -88,7 +88,7 @@ Enable GitHub Pages in your repository settings: go to **Settings → Pages** an
> **Tip:** Replace `X.Y.Z` with a real YiiPress version tag for reproducible, stable builds. The action builds to `_site` by default for GitHub Pages. See [GitHub Actions](github-actions.md) for custom output directories and other inputs.
-For project sites such as `https://user.github.io/project/`, set `base_url` to the full deployed URL including the project path. YiiPress uses that path when rendering root-relative redirect targets, so `redirect_to: /blog/` points to `/project/blog/` in browser-facing redirect HTML. Root-relative local asset links in rendered HTML are emitted relative to each page so images and other copied assets stay valid under the same deployment path.
+For project sites such as `https://user.github.io/project/`, set `base_url` to the full deployed URL including the project path. YiiPress uses that path when rendering root-relative redirect targets, so `redirect_to: /blog/` points to `/project/blog/` in browser-facing redirect HTML. Internal links generated by built-in templates and processors are emitted relative to each page, while feeds, sitemaps, canonical URLs, and redirect pages use absolute or browser-facing URLs with the configured project path. Custom templates should use the `$url()` helper for internal links and `Asset::url()` for copied assets.
> **Real-world example:** YiiPress documentation is built from the nightly binary image after the package workflow succeeds — see [`.github/workflows/build-docs.yml`](https://github.com/yiipress/engine/blob/master/.github/workflows/build-docs.yml) in this repository. Site repositories should use the release action above with a fixed version.
diff --git a/docs/templates.md b/docs/templates.md
index b9e3454..6f3c8ea 100644
--- a/docs/templates.md
+++ b/docs/templates.md
@@ -232,7 +232,7 @@ Example:
/partials/`:
```php
<?= $h($title) ?>
- #php
+Home
+```
+
+It keeps links valid for subdirectory deployments such as GitHub Pages project sites.
Additional helpers available via static methods:
diff --git a/psalm-baseline.xml b/psalm-baseline.xml
index e1948bf..aecee89 100644
--- a/psalm-baseline.xml
+++ b/psalm-baseline.xml
@@ -87,14 +87,6 @@
-
-
-
- templateResolver->resolve('errors/404', $siteConfig->theme)]]>
-
-
-
-
-
-
- resolvePath($path);
- $permalink = $this->fileToPermalink[$resolved] ?? null;
-
- if ($permalink === null) {
- return $matches[0];
- }
-
- if ($this->currentPermalink !== '') {
- $rootPath = RelativePathHelper::rootPath($this->currentPermalink);
- $permalink = RelativePathHelper::relativize($permalink, $rootPath);
- }
-
- return '[' . $text . '](' . $permalink . $fragment . ')';
- },
- $markdown,
- )]]>
-
-
]*>.*?<\/code>|]*>.*?<\/a>/is';
@@ -25,6 +26,11 @@ public function __construct(
private string $rootPath = '/',
) {}
+ public function applyRootPath(string $rootPath): void
+ {
+ $this->rootPath = $rootPath;
+ }
+
public function process(string $content, Entry $entry): string
{
if (!str_contains($content, '#')) {
@@ -70,7 +76,7 @@ private function convertHashtags(string $text): string
function (array $matches): string {
$tagDisplay = $matches[1];
$tagUrl = mb_strtolower($tagDisplay);
- $url = $this->rootPath . 'tags/' . $tagUrl . '/';
+ $url = UrlResolver::sitePath('/tags/' . $tagUrl . '/', $this->rootPath);
return '#' . htmlspecialchars($tagDisplay, ENT_QUOTES, 'UTF-8') . ' ';
},
$text
diff --git a/src/Render/NavigationRenderer.php b/src/Render/NavigationRenderer.php
index a860459..a665b9e 100644
--- a/src/Render/NavigationRenderer.php
+++ b/src/Render/NavigationRenderer.php
@@ -4,7 +4,7 @@
namespace YiiPress\Render;
-use YiiPress\Build\RelativePathHelper;
+use YiiPress\Build\UrlResolver;
use YiiPress\Content\Model\Navigation;
use YiiPress\Content\Model\NavigationItem;
use Yiisoft\Html\Html;
@@ -75,7 +75,7 @@ private static function renderItems(
$html .= '';
$url = str_starts_with($item->url, '/')
- ? RelativePathHelper::relativize($item->url, $rootPath)
+ ? UrlResolver::relativeUrl($item->url, $rootPath)
: $item->url;
$title = $item->resolveTitle($language, $defaultLanguage);
$attributes = self::localizedTitleAttributes($item);
diff --git a/tests/Unit/Build/EntryRendererTest.php b/tests/Unit/Build/EntryRendererTest.php
index 76283fe..1e6bb99 100644
--- a/tests/Unit/Build/EntryRendererTest.php
+++ b/tests/Unit/Build/EntryRendererTest.php
@@ -18,6 +18,9 @@
use YiiPress\Hook\RenderFinishedEvent;
use YiiPress\Hook\RenderStartedEvent;
use YiiPress\Processor\ContentProcessorPipeline;
+use YiiPress\Processor\MarkdownProcessor;
+use YiiPress\Processor\TagLinkProcessor;
+use YiiPress\Render\MarkdownRenderer;
use DateTimeImmutable;
use FilesystemIterator;
use PHPUnit\Framework\TestCase;
@@ -382,6 +385,27 @@ public function testInlineTagsAreFilteredFromTagsList(): void
assertStringContainsString('"tag">yii', $html);
}
+ public function testInlineTagLinksUseCurrentPageRootPath(): void
+ {
+ $entryFile = $this->contentDir . '/blog/post.md';
+ file_put_contents($entryFile, "---\ntitle: Tagged Post\n---\n\n#frankenphp #php\n");
+
+ $entry = $this->createEntry(filePath: $entryFile, title: 'Tagged Post');
+ $renderer = new EntryRenderer(
+ new ContentProcessorPipeline(
+ new MarkdownProcessor(new MarkdownRenderer()),
+ new TagLinkProcessor(),
+ ),
+ $this->createTemplateResolver(),
+ contentDir: $this->contentDir,
+ );
+ $html = $renderer->render($this->createSiteConfig(), $entry, '/blog/frankenphp-got-faster/');
+
+ assertStringContainsString('href="../../tags/frankenphp/" class="tag-link">#frankenphp', $html);
+ assertStringContainsString('href="../../tags/php/" class="tag-link">#php', $html);
+ assertStringNotContainsString('href="/tags/frankenphp/"', $html);
+ }
+
public function testCustomLayoutReceivesAllVariables(): void
{
mkdir($this->contentDir . '/templates', 0o755, true);
diff --git a/tests/Unit/Build/FeedGeneratorTest.php b/tests/Unit/Build/FeedGeneratorTest.php
index 0857471..ea35441 100644
--- a/tests/Unit/Build/FeedGeneratorTest.php
+++ b/tests/Unit/Build/FeedGeneratorTest.php
@@ -11,6 +11,7 @@
use YiiPress\Processor\ContentProcessorInterface;
use YiiPress\Processor\ContentProcessorPipeline;
use YiiPress\Processor\MarkdownProcessor;
+use YiiPress\Processor\TagLinkProcessor;
use YiiPress\Render\MarkdownRenderer;
use DateTimeImmutable;
use PHPUnit\Framework\TestCase;
@@ -232,6 +233,59 @@ public function process(string $content, Entry $entry): string
$this->assertSame(1, $processor->calls);
}
+ public function testInlineTagLinksUseAbsolutePublicRootInFeedContent(): void
+ {
+ $siteConfig = new SiteConfig(
+ title: 'Project Site',
+ description: 'A project site',
+ baseUrl: 'https://samdark.github.io/blog/',
+ defaultLanguage: 'en',
+ charset: 'UTF-8',
+ defaultAuthor: 'john-doe',
+ dateFormat: 'F j, Y',
+ entriesPerPage: 10,
+ permalink: '/:collection/:slug/',
+ taxonomies: ['tags'],
+ params: [],
+ );
+ file_put_contents($this->tempFile, "Testing #php.\n");
+
+ $entry = new Entry(
+ filePath: $this->tempFile,
+ collection: 'blog',
+ slug: 'first-post',
+ title: 'First Post',
+ date: new DateTimeImmutable('2024-03-15'),
+ draft: false,
+ tags: ['php'],
+ categories: [],
+ authors: ['john-doe'],
+ summary: '',
+ permalink: '',
+ layout: '',
+ theme: '',
+ weight: 0,
+ language: 'en',
+ redirectTo: '',
+ extra: [],
+ bodyOffset: 0,
+ bodyLength: (int) filesize($this->tempFile),
+ );
+
+ $generator = new FeedGenerator(new ContentProcessorPipeline(
+ new MarkdownProcessor(new MarkdownRenderer()),
+ new TagLinkProcessor(),
+ ));
+
+ $atom = $generator->generateAtom($siteConfig, $this->collection, [$entry]);
+ $rss = $generator->generateRss($siteConfig, $this->collection, [$entry]);
+
+ assertStringContainsString('href="https://samdark.github.io/blog/tags/php/"', $atom);
+ assertStringContainsString('href="https://samdark.github.io/blog/tags/php/"', $rss);
+ assertStringNotContainsString('href="/tags/php/"', $atom);
+ assertStringNotContainsString('href="/tags/php/"', $rss);
+ }
+
/**
* @return list
*/
diff --git a/tests/Unit/Build/PublicUrlResolverTest.php b/tests/Unit/Build/PublicUrlResolverTest.php
index 63ff848..dc99322 100644
--- a/tests/Unit/Build/PublicUrlResolverTest.php
+++ b/tests/Unit/Build/PublicUrlResolverTest.php
@@ -4,7 +4,7 @@
namespace YiiPress\Tests\Unit\Build;
-use YiiPress\Build\PublicUrlResolver;
+use YiiPress\Build\UrlResolver;
use YiiPress\Content\Model\SiteConfig;
use PHPUnit\Framework\TestCase;
@@ -14,33 +14,55 @@
final class PublicUrlResolverTest extends TestCase
{
+ public function testBuildsSitePathRelativeToCurrentPageRoot(): void
+ {
+ assertSame('../../tags/php/', UrlResolver::sitePath('/tags/php/', '../../'));
+ assertSame('./tags/php/', UrlResolver::sitePath('tags/php/', './'));
+ assertSame('https://example.github.io/blog/tags/php/', UrlResolver::sitePath('/tags/php/', 'https://example.github.io/blog/'));
+ }
+
+ public function testLeavesExternalAndSpecialSitePathsAlone(): void
+ {
+ assertSame('https://other.example/tags/php/', UrlResolver::sitePath('https://other.example/tags/php/', '../../'));
+ assertSame('#section', UrlResolver::sitePath('#section', '../../'));
+ assertSame('mailto:test@example.com', UrlResolver::sitePath('mailto:test@example.com', '../../'));
+ }
+
public function testPrefixesSiteRootUrlWithBasePath(): void
{
$siteConfig = $this->createSiteConfig('https://example.github.io/blog/');
- assertSame('/blog/posts/', PublicUrlResolver::browserUrl($siteConfig, '/posts/'));
+ assertSame('/blog/posts/', UrlResolver::browserUrl($siteConfig, '/posts/'));
}
public function testLeavesSiteRootUrlAloneWhenBaseUrlHasNoPath(): void
{
$siteConfig = $this->createSiteConfig('https://example.com/');
- assertSame('/posts/', PublicUrlResolver::browserUrl($siteConfig, '/posts/'));
+ assertSame('/posts/', UrlResolver::browserUrl($siteConfig, '/posts/'));
}
public function testLeavesAbsoluteUrlAlone(): void
{
$siteConfig = $this->createSiteConfig('https://example.github.io/blog/');
- assertSame('https://other.example/posts/', PublicUrlResolver::browserUrl($siteConfig, 'https://other.example/posts/'));
+ assertSame('https://other.example/posts/', UrlResolver::browserUrl($siteConfig, 'https://other.example/posts/'));
+ }
+
+ public function testAbsoluteUrlPrefixesOriginAndBasePath(): void
+ {
+ $siteConfig = $this->createSiteConfig('https://example.github.io/blog/');
+
+ assertSame('https://example.github.io/blog/tags/php/', UrlResolver::absoluteUrl($siteConfig, '/tags/php/'));
+ assertSame('https://example.github.io/blog/tags/php/', UrlResolver::absoluteUrl($siteConfig, 'tags/php/'));
}
public function testDetectsSelfRedirectAfterBasePathResolution(): void
{
$siteConfig = $this->createSiteConfig('https://example.github.io/blog/');
- assertTrue(PublicUrlResolver::isSamePublicUrl($siteConfig, '/', '/'));
- assertFalse(PublicUrlResolver::isSamePublicUrl($siteConfig, '/', '/blog/'));
+ assertTrue(UrlResolver::isSamePublicUrl($siteConfig, '/', '/'));
+ assertFalse(UrlResolver::isSamePublicUrl($siteConfig, '/', '/blog/'));
}
private function createSiteConfig(string $baseUrl): SiteConfig
diff --git a/tests/Unit/Console/BuildCommandTest.php b/tests/Unit/Console/BuildCommandTest.php
index 5f1fb8a..7fc4b33 100644
--- a/tests/Unit/Console/BuildCommandTest.php
+++ b/tests/Unit/Console/BuildCommandTest.php
@@ -1233,6 +1233,92 @@ public function testBuildRewritesRootRelativeContentImageForSubdirectoryDeployme
assertStringContainsString('content="https://samdark.github.io/blog/blog/assets/photo.jpg"', $html);
}
+ public function testBuildUsesUniformInternalUrlsForSubdirectoryDeployment(): void
+ {
+ $tempDir = sys_get_temp_dir() . '/yiipress-build-project-url-test-' . uniqid();
+ $contentDir = $tempDir . '/content';
+ $outputDir = $tempDir . '/output';
+ mkdir($contentDir . '/blog', 0o755, true);
+ mkdir($contentDir . '/authors', 0o755, true);
+ $this->tempContentDirs[] = $tempDir;
+
+ file_put_contents(
+ $contentDir . '/config.yaml',
+ "title: Project Site\n"
+ . "base_url: https://samdark.github.io/blog/\n"
+ . "languages: [en]\n"
+ . "author_pages: true\n"
+ . "search: true\n"
+ . "taxonomies:\n"
+ . " - tags\n"
+ . " - categories\n",
+ );
+ file_put_contents($contentDir . '/blog/_collection.yaml', "title: Blog\npermalink: /blog/:slug/\nfeed: true\n");
+ file_put_contents($contentDir . '/authors/john-doe.md', "---\ntitle: John Doe\n---\n\nAuthor bio.\n");
+ file_put_contents(
+ $contentDir . '/blog/post.md',
+ "---\n"
+ . "title: Post\n"
+ . "date: 2024-03-15\n"
+ . "tags: [php, yii]\n"
+ . "categories: [performance]\n"
+ . "authors: [john-doe]\n"
+ . "---\n\n"
+ . "Inline #php tag.\n",
+ );
+
+ $yii = dirname(__DIR__, 3) . '/yii';
+ exec(
+ $yii . ' build'
+ . ' --content-dir=' . escapeshellarg($contentDir)
+ . ' --output-dir=' . escapeshellarg($outputDir)
+ . ' --no-cache'
+ . ' 2>&1',
+ $output,
+ $exitCode,
+ );
+
+ assertSame(0, $exitCode, implode("\n", $output));
+
+ $entryHtml = file_get_contents($outputDir . '/blog/post/index.html');
+ assertNotFalse($entryHtml);
+ assertStringContainsString('href="../../"', $entryHtml);
+ assertStringContainsString('data-root="../../"', $entryHtml);
+ assertStringContainsString('href="../../authors/john-doe/"', $entryHtml);
+ assertStringContainsString('href="../../tags/php/" class="tag-link">#php', $entryHtml);
+ assertStringContainsString('href="../../tags/yii/" class="tag-link">#yii', $entryHtml);
+ assertStringContainsString('href="../../categories/performance/" class="category">performance', $entryHtml);
+ assertStringNotContainsString('href="/tags/', $entryHtml);
+ assertStringNotContainsString('href="/categories/', $entryHtml);
+ assertStringNotContainsString('href="/authors/', $entryHtml);
+
+ $listingHtml = file_get_contents($outputDir . '/blog/index.html');
+ assertNotFalse($listingHtml);
+ assertStringContainsString('href="../blog/archive/"', $listingHtml);
+ assertStringContainsString('href="../blog/rss.xml"', $listingHtml);
+ assertStringContainsString('href="../blog/feed.xml"', $listingHtml);
+
+ $tagsIndexHtml = file_get_contents($outputDir . '/tags/index.html');
+ assertNotFalse($tagsIndexHtml);
+ assertStringContainsString('href="../tags/php/"', $tagsIndexHtml);
+ assertStringContainsString('href="../tags/yii/"', $tagsIndexHtml);
+
+ $authorsIndexHtml = file_get_contents($outputDir . '/authors/index.html');
+ assertNotFalse($authorsIndexHtml);
+ assertStringContainsString('href="../authors/john-doe/"', $authorsIndexHtml);
+
+ $feed = file_get_contents($outputDir . '/blog/feed.xml');
+ assertNotFalse($feed);
+ assertStringContainsString('https://samdark.github.io/blog/blog/post/', $feed);
+ assertStringContainsString('href="https://samdark.github.io/blog/tags/php/"', $feed);
+ assertStringNotContainsString('href="/tags/php/"', $feed);
+
+ $sitemap = file_get_contents($outputDir . '/sitemap.xml');
+ assertNotFalse($sitemap);
+ assertStringContainsString('https://samdark.github.io/blog/blog/post/', $sitemap);
+ assertStringContainsString('https://samdark.github.io/blog/authors/john-doe/', $sitemap);
+ }
+
private function manifestPath(): string
{
return RuntimePaths::cachePath(dirname(__DIR__, 3)) . '/build-manifest-' . hash('xxh128', $this->outputDir) . '.json';
diff --git a/themes/minimal/archive_index.php b/themes/minimal/archive_index.php
index edd2c10..8b55125 100644
--- a/themes/minimal/archive_index.php
+++ b/themes/minimal/archive_index.php
@@ -19,6 +19,7 @@
* @var array> $uiCatalogs
* @var YiiPress\I18n\UiText $ui
* @var Closure(string, int, ?string, bool): string $h
+ * @var Closure(string): string $url
* @var Closure(string, array): string $t
*/
@@ -38,7 +39,7 @@
diff --git a/themes/minimal/archive_monthly.php b/themes/minimal/archive_monthly.php
index f1f2559..5c9b771 100644
--- a/themes/minimal/archive_monthly.php
+++ b/themes/minimal/archive_monthly.php
@@ -22,6 +22,7 @@
* @var array> $uiCatalogs
* @var YiiPress\I18n\UiText $ui
* @var Closure(string, int, ?string, bool): string $h
+ * @var Closure(string): string $url
* @var Closure(string, array): string $t
*/
@@ -39,7 +40,7 @@
:
-
← $year])) ?>
+
← $year])) ?>
diff --git a/themes/minimal/archive_yearly.php b/themes/minimal/archive_yearly.php
index de8b473..cc13e60 100644
--- a/themes/minimal/archive_yearly.php
+++ b/themes/minimal/archive_yearly.php
@@ -21,6 +21,7 @@
* @var array> $uiCatalogs
* @var YiiPress\I18n\UiText $ui
* @var Closure(string, int, ?string, bool): string $h
+ * @var Closure(string): string $url
*/
use YiiPress\Content\Model\Navigation;
@@ -41,7 +42,7 @@
diff --git a/themes/minimal/collection_listing.php b/themes/minimal/collection_listing.php
index a94947a..77a4240 100644
--- a/themes/minimal/collection_listing.php
+++ b/themes/minimal/collection_listing.php
@@ -20,6 +20,7 @@
* @var array> $uiCatalogs
* @var YiiPress\I18n\UiText $ui
* @var Closure(string, int, ?string, bool): string $h
+ * @var Closure(string): string $url
* @var Closure(string, array): string $t
*/
@@ -42,10 +43,10 @@
diff --git a/themes/minimal/partials/head.php b/themes/minimal/partials/head.php
index 9e742dc..d13b97e 100644
--- a/themes/minimal/partials/head.php
+++ b/themes/minimal/partials/head.php
@@ -13,6 +13,7 @@
* @var array> $uiCatalogs
* @var YiiPress\I18n\UiText $ui
* @var Closure(string, int, ?string, bool): string $h
+ * @var Closure(string): string $url
* @var Closure(string, array): string $t
*/
@@ -179,8 +180,8 @@
$uiLanguages
* @var Closure(string, int, ?string, bool): string $h
+ * @var Closure(string): string $url
* @var Closure(string, array): string $t
* @var Closure(string): string $languageName
*/
@@ -23,7 +24,7 @@
?>