refactor: immutable urls with canonical/norobot

Author: innocenzi

bun.lock

@@ -4,22 +4,22 @@
     "": {
       "dependencies": {
         "highlight.js": "^11.11.1",
-        "puppeteer": "24.15.0",
+        "puppeteer": "^24.11.2",
       },
       "devDependencies": {
         "@fontsource-variable/kantumruy-pro": "^5.2.6",
         "@fontsource-variable/public-sans": "^5.2.6",
         "@tailwindcss/typography": "^0.5.16",
         "@tailwindcss/vite": "^4.1.11",
-        "@vitejs/plugin-vue": "6.0.1",
-        "@vueuse/core": "13.6.0",
+        "@vitejs/plugin-vue": "^6.0.0",
+        "@vueuse/core": "^13.5.0",
         "fuse.js": "^7.1.0",
-        "reka-ui": "2.4.1",
+        "reka-ui": "^2.3.2",
         "tailwindcss": "^4.1.11",
         "typescript": "^5.8.3",
         "vite": "^6.3.5",
         "vite-plugin-tempest": "^0.0.2",
-        "vue": "3.5.18",
+        "vue": "^3.5.17",
       },
     },
   },

src/Web/Documentation/Chapter.php

@@ -23,7 +23,22 @@ public function __construct(
 
     public function getUri(): string
     {
-        return uri(DocumentationController::class, version: $this->version, category: $this->category, slug: $this->slug);
+        return uri(
+            DocumentationController::class,
+            version: $this->version,
+            category: $this->category,
+            slug: $this->slug,
+        );
+    }
+
+    public function getCanonicalUri(): string
+    {
+        return uri(
+            DocumentationController::class,
+            version: $this->version->default(),
+            category: $this->category,
+            slug: $this->slug,
+        );
     }
 
     public function getMetaUri(): string

src/Web/Documentation/ChapterRepository.php

@@ -7,7 +7,10 @@
 use App\Support\HasMemoization;
 use League\CommonMark\Extension\FrontMatter\Output\RenderedContentWithFrontMatter;
 use League\CommonMark\MarkdownConverter;
+use RuntimeException;
 use Spatie\YamlFrontMatter\YamlFrontMatter;
+use Tempest\Http\HttpRequestFailed;
+use Tempest\Http\Status;
 use Tempest\Support\Arr\ImmutableArray;
 
 use function Tempest\root_path;
@@ -29,8 +32,14 @@ public function find(Version $version, string $category, string $slug): ?Chapter
     {
         $category = replace($category, '/^\d+-/', '');
         $slug = replace($slug, '/^\d+-/', '');
+        $directory = __DIR__ . "/content/{$version->getUrlSegment()}";
+
+        if (! is_dir($directory)) {
+            throw new RuntimeException("Documentation for version {$version->value} has not been fetched. Run `tempest docs:pull {$version->value}`.");
+        }
+
         $path = ImmutableArray::createFrom(recursive_search(
-            folder: __DIR__ . "/content/{$version->value}",
+            folder: $directory,
             pattern: sprintf("#.*\/(\d+-)?%s\/(\d+-)?%s\.md#", preg_quote($category, '#'), preg_quote($slug, '#')),
         ))->sort()->first();
 
@@ -68,7 +77,7 @@ public function all(Version $version, string $category = '*'): ImmutableArray
     {
         return $this->memoize(
             $version->value . $category,
-            fn () => arr(glob(__DIR__ . "/content/{$version->value}/*{$category}/*.md"))
+            fn () => arr(glob(__DIR__ . "/content/{$version->getUrlSegment()}/*{$category}/*.md"))
                 ->map(function (string $path) use ($version) {
                     $content = file_get_contents($path);
                     $category = str($path)->beforeLast('/')->afterLast('/')->replaceRegex('/^\d+-/', '');

src/Web/Documentation/ChapterView.php

@@ -118,7 +118,7 @@ public function previousChapter(): ?Chapter
     public function categories(): array
     {
         return map_iterable(
-            array: glob(__DIR__ . "/content/{$this->version->value}/*", flags: GLOB_ONLYDIR),
+            array: glob(__DIR__ . "/content/{$this->version->getUrlSegment()}/*", flags: GLOB_ONLYDIR),
             map: fn (string $path) => str($path)->afterLast('/')->replaceRegex('/^\d+-/', '')->toString(),
         );
     }

src/Web/Documentation/DefaultDocumentationDataProvider.php

@@ -9,6 +9,7 @@
 use Tempest\Http\Responses\Redirect;
 use Tempest\Router\Get;
 use Tempest\Router\StaticPage;
+use Tempest\Support\Arr\ImmutableArray;
 use Tempest\Support\Str\ImmutableString;
 use Tempest\View\View;
 
@@ -20,58 +21,48 @@
 {
     #[Get('/current/{path:.*}')]
     #[Get('/main/{path:.*}')]
-    public function docsRedirect(string $path): Redirect
+    #[Get('/docs/{path:.*}')]
+    public function redirect(string $path): Redirect
     {
-        return new Redirect(sprintf('/%s/%s', Version::default()->value, $path));
+        return new Redirect(sprintf('/%s/%s', Version::default()->getUrlSegment(), $path));
     }
 
-    #[Get('/docs')]
     #[Get('/documentation')]
-    #[Get('/main/framework/getting-started')]
     public function index(): Redirect
     {
         $version = Version::default();
 
-        $category = arr(glob(__DIR__ . "/content/{$version->value}/*", flags: GLOB_ONLYDIR))
+        $category = arr(glob(__DIR__ . "/content/{$version->getUrlSegment()}/*", flags: GLOB_ONLYDIR))
+            ->tap(fn (ImmutableArray $files) => $files->isEmpty() ? throw new \RuntimeException('Documentation has not been fetched. Run `tempest docs:pull`.') : null)
             ->sort()
             ->mapFirstTo(ImmutableString::class)
             ->basename()
             ->toString();
 
-        $slug = arr(glob(__DIR__ . "/content/{$version->value}/{$category}/*.md"))
+        $slug = arr(glob(__DIR__ . "/content/{$version->getUrlSegment()}/{$category}/*.md"))
             ->map(fn (string $path) => before_first(basename($path), '.'))
             ->sort()
             ->mapFirstTo(ImmutableString::class)
             ->basename()
             ->toString();
 
         return new Redirect(uri(
-            [self::class, 'default'],
+            [self::class, '__invoke'],
+            version: $version,
             category: str_replace('0-', '', $category),
             slug: str_replace('01-', '', $slug),
         ));
     }
 
-    #[StaticPage(DefaultDocumentationDataProvider::class)]
-    #[Get('/docs/{category}/{slug}')]
-    public function default(string $category, string $slug, ChapterRepository $chapterRepository): View|Response
-    {
-        return $this->chapterView(Version::default(), $category, $slug, $chapterRepository) ?? new NotFound();
-    }
-
     #[StaticPage(DocumentationDataProvider::class)]
     #[Get('/{version}/{category}/{slug}')]
     public function __invoke(string $version, string $category, string $slug, ChapterRepository $chapterRepository): View|Response
     {
-        if ($version === Version::default()->value) {
-            return new Redirect(uri([self::class, 'default'], category: $category, slug: $slug));
-        }
-
         if (is_null($version = Version::tryFromString($version))) {
             return new NotFound();
         }
 
-        return $this->chapterView($version, $category, $slug, $chapterRepository) ?? new NotFound();
+        return $this->chapterView($version, $category, $slug, $chapterRepository) ?? new Redirect(uri(self::class, 'index'));
     }
 
     private function chapterView(Version $version, string $category, string $slug, ChapterRepository $chapterRepository): ?ChapterView

src/Web/Documentation/DocumentationController.php

@@ -5,6 +5,7 @@
 use Tempest\Core\Priority;
 use Tempest\Http\Request;
 use Tempest\Http\Response;
+use Tempest\Http\Responses\NotFound;
 use Tempest\Http\Responses\Redirect;
 use Tempest\Router\HttpMiddleware;
 use Tempest\Router\HttpMiddlewareCallable;
@@ -15,35 +16,41 @@
 use function Tempest\Support\Arr\get_by_key;
 use function Tempest\Support\Regex\matches;
 use function Tempest\Support\str;
+use function Tempest\uri;
 
 #[Priority(Priority::HIGHEST)]
 final readonly class RedirectMiddleware implements HttpMiddleware
 {
     public function __construct(
         private Router $router,
+        private MatchedRoute $route,
     ) {}
 
     #[\Override]
     public function __invoke(Request $request, HttpMiddlewareCallable $next): Response
     {
         $path = str($request->path);
         $response = $next($request);
-        $matched = get(MatchedRoute::class);
+        $version = Version::tryFromString(get_by_key($this->route->params, 'version'));
 
         // If not a docs page, let's just continue normal flow
-        if ($matched->route->uri !== '/{version}/{category}/{slug}') {
+        if ($this->route->route->uri !== '/{version}/{category}/{slug}') {
             return $response;
         }
 
         // Redirect to slugs without numbers
-        if (matches($matched->params['category'], '/^\d+-/') || matches($matched->params['slug'], '/^\d+-/')) {
+        if (matches($this->route->params['category'], '/^\d+-/') || matches($this->route->params['slug'], '/^\d+-/')) {
             return new Redirect($path->replaceRegex('/\/\d+-/', '/'));
         }
 
+        // If no version found, 404
+        if ($version === null) {
+            return new Redirect(uri([DocumentationController::class, 'index']));
+        }
+
         // Redirect to actual version
-        $version = Version::tryFromString(get_by_key($matched->params, 'version'));
-        if ($version->value !== $matched->params['version']) {
-            return new Redirect($path->replace("/{$matched->params['version']}/", "/{$version->value}/"));
+        if ($version->getUrlSegment() !== $this->route->params['version']) {
+            return new Redirect($path->replace("/{$this->route->params['version']}/", "/{$version->getUrlSegment()}/"));
         }
 
         return $response;

src/Web/Documentation/RedirectMiddleware.php

@@ -8,9 +8,25 @@ enum Version: string
 {
     use IsEnumHelper;
 
-    case VERSION_1 = 'main';
+    case VERSION_1 = '1.x';
     case VERSION_2 = '2.x';
 
+    public function isNext(): bool
+    {
+        return match ($this) {
+            self::VERSION_2 => true,
+            default => false,
+        };
+    }
+
+    public function isCurrent(): bool
+    {
+        return match ($this) {
+            self::VERSION_1 => true,
+            default => false,
+        };
+    }
+
     public function getBranch(): string
     {
         return match ($this) {
@@ -22,15 +38,21 @@ public function getBranch(): string
     public function getUrlSegment(): string
     {
         return match ($this) {
-            self::VERSION_1 => 'main',
+            self::VERSION_1 => '1.x',
             self::VERSION_2 => '2.x',
         };
     }
 
+    public function isPrevious(): bool
+    {
+        return ! $this->isNext() && ! $this->isCurrent();
+    }
+
     public static function tryFromString(?string $case): ?static
     {
         return match ($case) {
-            'default', 'current', null => self::default(),
+            'default', 'current', 'main', null => self::default(),
+            'next' => self::VERSION_2,
             default => self::tryFrom($case),
         };
     }