README

Folio Markdown 是 Laravel Folio 页面路由扩展，允许使用 .md 和 .blade.md 文件创建路由。这简化了在 Laravel 应用程序中生成路由的过程。

概述

Laravel Folio 允许你在应用程序的 resources/views/pages 目录中创建 Blade 模板来生成路由。Folio Markdown 通过允许你在同一目录中使用 Markdown 文件创建路由来增强此功能。

例如，要创建可在 /greeting URL 访问的页面，你可以在 resources/views/pages 目录中创建一个 greeting.md 文件

---
view: layouts.app
title: Greetings From Space!
---

# Greetings earthlings!

...

YAML 前端元数据被转换为视图模板的变量，Markdown 内容作为 $slot 变量传递给视图模板。

安装步骤

按照以下步骤安装和设置 Folio Markdown

1. 安装 Laravel Folio: 使用 Composer 将 Laravel Folio 安装到你的 Laravel 应用程序中

composer require laravel/folio:^1.0@beta

1. 执行 folio:install: 运行 folio:install Artisan 命令。这将安装 Folio 的服务提供程序并注册 Folio 查找路由或页面的目录

php artisan folio:install

1. 安装 Folio Markdown 包: 使用 Composer 安装 Folio Markdown 包

composer require snellingio/folio-markdown:^1.0@beta

1. 注册 Folio Markdown: 在你的 App\Providers\FolioServiceProvider 文件中，使用 FolioMarkdown Facade 调用 register 方法

use Snelling\FolioMarkdown\Facades\FolioMarkdown;

class FolioServiceProvider extends ServiceProvider
{

    /**
     * Bootstrap services.
     */
    public function boot(): void
    {
        // Place your Folio calls before the register method
        Folio::path(resource_path('views/pages'))->middleware([
            '*' => [
                //
            ],
        ]);
        
        // Register Folio Markdown at the bottom of the boot method
        FolioMarkdown::register();
    }
}

完成这些步骤后，你现在可以使用 Markdown 文件在你的 Laravel 应用程序中创建路由。

快速亮点

Folio Markdown 支持各种功能，包括

• 文件扩展名：具有 .md 扩展名的文件被处理为 Markdown 文件。具有 .blade.md 扩展名的文件首先作为 Blade 模板处理，然后作为 Markdown 文件处理，允许在 Markdown 文件中使用特定的 Blade 指令。但是，由于每个文件单独渲染，因此一些跨组件的 Blade 指令（如 @push 和 @section）可能不起作用。

• 视图模板：要指定视图模板，在页面的前端元数据中使用 view 键。页面内容作为 $slot 变量传递给视图模板。

• 处理软删除模型：默认情况下，在解析隐式模型绑定时不会检索软删除的模型。如果你希望 Folio Markdown 也检索这些模型，请在页面的前端元数据中添加 withTrashed 键。

• 中间件：要将中间件应用于特定页面，请在页面的前端元数据中添加 middleware 键。或者，要在一组页面中应用中间件，请在调用 Folio::path 方法后链式调用 middleware 方法。

• 前端元数据：你可以在页面中添加任何额外的元数据作为视图数据传递。例如，你可以在页面的前端元数据中添加一个 title 键，它将作为 $title 变量传递给视图模板。

请参阅下面的详细指南以全面了解每个功能。

理解文件扩展名

以 .md 结尾的文件自动识别并处理为 Markdown 文件。如果文件以 .blade.md 结尾，它将首先被处理为 Blade 模板，然后作为 Markdown 文件处理。这允许你在 Markdown 文件中使用特定的 Blade 指令。但是，要注意，一些跨组件使用的 Blade 指令（如 @push 和 @section）可能不起作用，因为每个文件都是单独处理的。

Markdown 扩展

在底层，Folio Markdown 使用了 Spatie Laravel Markdown 包。

虽然 Folio Markdown 尊重 Spatie Laravel Markdown 包的配置，但目前通过 Shiki 的代码高亮功能已被禁用（@TODO：需要创建一个 issue！）。

如何使用视图模板

要使用视图模板，你需要在页面的前端元信息中包含 view 键，如下所示

---
view: app.layouts
---

# Hello World!

然后页面内容将作为 $slot 变量传递给视图模板。

与软删除模型协同工作

默认情况下，在解析隐式模型绑定时不会包括软删除模型。如果你想让 Folio Markdown 也包括这些模型，请在页面的前端元信息中添加 withTrashed 键

---
withTrashed: true
---

# Hello Trashed!

应用中间件

如果你想为特定页面使用中间件，请在页面的前端元信息中包含 middleware 键

---
middleware: auth
---

# Hello Middleware!

如果你想为一组页面使用中间件，可以在调用 Folio::path 方法之后链式调用 middleware 方法。

添加更多前端元信息

你可以在你的页面中添加任何额外的前端元信息。例如，你可能想在页面的前端元信息中添加一个 title 键

---
view: app.layouts
title: Hello World!
---

这将作为 $title 变量传递给视图模板。这适用于所有前端元信息键。

你熟悉并喜爱的同一 Folio

创建子页面

要在 Folio 中创建子页面，你需要在现有目录中创建一个新的目录。例如，如果你想创建一个可以通过 /user/profile 访问的页面，你会在 pages/user 目录中创建一个 profile.md 模板，如下所示

# pages/user/profile.md → /user/profile

设置默认页面

有时，你可能想要将特定页面设置为目录的默认页面。你可以通过在 Folio 目录中放置一个 index.md 或 index.blade.md 模板来实现这一点。然后，对该目录根的任何请求都将被重定向到该页面

# pages/index.md → /
# pages/users/index.md → /users

在您的页面中使用 URL 段

可能有时你需要使用传入请求的 URL 的一部分在你的页面中。例如，你可能需要访问显示的用户配置文件的 "ID"。为此，你可以在方括号中包含页面文件名的一部分

# pages/users/[id].blade.md → /users/1

然后，你可以将这些捕获到的段作为变量在你的 .blade.md 模板中或父 view 组件中使用

<div>
    User {{ $id }}
</div>

要捕获多个段，可以在封装的段前加上三个点 ...

# pages/users/[...ids].blade.md → /users/1/2/3

在捕获多个段时，捕获到的段将被注入到页面中作为一个数组

<ul>
    @foreach ($ids as $id)
    <li>User {{ $id }}</li>
    @endforeach
</ul>

将 URL 段链接到模型

如果你的页面模板的文件名中的通配符段与你的应用程序的 Eloquent 模型之一匹配，Folio 将自动将其链接到 Laravel 的路由模型绑定功能，并尝试将解析出的模型实例注入到你的页面中

# pages/users/[User].md → /users/1
# pages/users/[User].blade.md → /users/1

捕获到的模型可以在你的 .blade.md 模板或父 view 组件中作为变量访问。模型的变量名将被转换为 "骆驼式"。

<div>
    User {{ $user->id }}
</div>

自定义模型键

如果你想使用除 id 之外的字段链接已绑定的 Eloquent 模型，你可以在页面的文件名中指定该字段。例如，具有文件名 [Post:slug].blade.md 的页面将尝试通过 slug 字段而不是 id 字段来链接绑定的模型。

指定模型位置

默认情况下，Folio 将在应用程序的 app/Models 目录中查找你的模型。但是，如果需要，你可以在模板的文件名中指定完整的模型类名

# pages/users/[.App.Models.User].blade.md → /users/1

在你的文件中编写 PHP 代码

如果你需要在你的文件中编写 PHP 代码，你必须以 .blade.md 结尾。

然后您可以使用 @php Blade 指令

@php
    if (! Auth::user()->can('view-posts', $user)) {
        abort(403);
    }

    $posts = $user->posts;
@endphp

@foreach ($posts as $post)
    <div>
        {{ $post->title }}
    </div>
@endforeach

请注意，在 Folio 中，<?php 和 ?> 标签仅用于 Folio 页面定义函数，如 middleware 和 withTrashed，这些在当前 Folio Markdown 中不受支持。

测试

composer test

变更日志

有关最近变更的更多信息，请参阅 变更日志

许可证

MIT 许可证 (MIT)。有关更多信息，请参阅 许可证文件