README

一个为您的filament面板添加知识库和文档的插件。

您的filament面板是否曾经迅速变得复杂？是否需要一个地方来记录所有功能？

Filament知识库就是为了这个原因而存在的！

使用我们的知识库包，您可以编写markdown文档文件来记录您包的每个功能，并为您的用户提供针对您产品的全面知识库。就在Filament内！

展示

为了更好地了解其工作原理，请观看视频展示

demo_preview.mp4

支持我们

您的支持对我们插件持续进步至关重要。我们感激至今为止所有为我们的旅程做出贡献的用户。

虽然我们的插件对所有用户开放，但如果您将其用于商业目的并认为它为您的业务增添了显著价值，我们恳请您考虑通过GitHub Sponsors支持我们。这种赞助将帮助我们进行持续的开发和维护，以保持我们的插件强大且更新。您提供的任何金额都将极大地帮助我们实现目标。加入我们，使这个插件变得更好，推动进一步的创新。

安装

您可以通过composer安装此包

composer require guava/filament-knowledge-base

请确保使用以下命令发布包资源

php artisan filament:assets

您可以使用以下命令发布配置文件

php artisan vendor:publish --tag="filament-knowledge-base-config"

这是发布配置文件的内容

return [
    'panel' => [
        'id' => env('FILAMENT_KB_ID', 'knowledge-base'),
        'path' => env('FILAMENT_KB_PATH', 'kb'),
    ],

    'docs-path' => env('FILAMENT_KB_DOCS_PATH', 'docs'),

    'model' => \Guava\FilamentKnowledgeBase\Models\FlatfileDocumentation::class,
    
    'cache' => [
        'prefix' => env('FILAMENT_KB_CACHE_PREFIX', 'filament_kb_'),
        'ttl' => env('FILAMENT_KB_CACHE_TTL', 86400),
    ],
];

简介

知识库面板

我们为您的整个知识库注册了一个独立的面板。这样，您就可以在一个地方详细记录您的功能。

模态预览

而不是立即将用户重定向到文档，该插件提供模态预览，它以可定制的模态形式呈现markdown，并可选地打开完整的文档页面。

您可以在自定义部分了解如何启用此功能。

全局搜索

知识库支持对您的所有markdown文件进行全局搜索，默认情况下会搜索markdown文件的标题和内容。这样，您的用户可以快速找到他们需要的内容。

存储

我们目前支持开箱即用的平面文件（存储在源项目中）存储。

您可以选择将文档存储在以下位置

Markdown文件（首选方法）
PHP类（用于复杂情况）

未来，我们计划还提供数据库驱动程序，以便您可以将文档存储在数据库中。

用法

注册插件

首先，在您想要访问知识库/文档的所有Filament面板中注册KnowledgeBasePlugin。

use Filament\Panel;
use Guava\FilamentKnowledgeBase\KnowledgeBasePlugin;
 
public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            // ...
            KnowledgeBasePlugin::make(),
        ])
}

确保您有一个自定义filament主题

请查阅这里了解如何创建一个。

您可以专门为知识库面板创建一个，或者如果您想与主面板（s）保持相同的设计，您可以直接重用面板的vite主题。

然后在您的 AppServiceProvider 注册方法中，使用以下方式配置知识库面板的 Vite 主题：

use Guava\FilamentKnowledgeBase\Filament\Panels\KnowledgeBasePanel;

KnowledgeBasePanel::configureUsing(
    fn(KnowledgeBasePanel $panel) => $panel
        ->viteTheme('resources/css/filament/admin/theme.css') // your filament vite theme path here 
);

构建 CSS

在每个纤维主题中，确保在 tailwind.config.js 中包含插件的 php 和 blade 文件，以确保 CSS 正确构建

{
    content: [
        //...

        './vendor/guava/filament-knowledge-base/src/**/*.php',
        './vendor/guava/filament-knowledge-base/resources/**/*.blade.php',
    ]
}

创建文档

要创建您的第一个文档，只需运行 docs:make，例如

php artisan docs:make prologue.getting-started

这将创建一个文件在 /docs/en/prologue/getting-started.md。

如果您想为特定区域创建文件，可以使用 --locale 选项（可以重复用于多个区域）

php artisan docs:make prologue.getting-started --locale=de --locale=en

这将为 de 和 en 区域创建文件。

如果您没有传递任何区域，它将自动在 /docs/{locale} 中为每个区域创建文档文件。

Markdown

在生成文档文件后，是时候编辑它了。

Markdown 文件由两部分组成，即 Front Matter 和 Content。

Front Matter

在 Front Matter 中，您可以自定义文档页面，例如标题、图标等

---
// Anything between these dashes is the front matter
title: My example documentation
icon: heroicon-o-book-open
---

Front Matter 选项

以下是当前 Front Matter 中可用的选项列表。

标题

允许您修改文档页面的标题。

---
title: My new title
---

图标

允许您修改文档页面的图标。

您可以使用任何 Blade UI 图标支持的名字，您已安装的。

---
icon: heroicon-o-user
---

顺序

允许您修改文档页面在其父级/组中的顺序。

较小的数字将首先显示。

---
order: 1
---

组

允许您定义文档页面的组（及其标题）。

---
group: Getting Started
---

父级

允许您定义文档页面的父级。

---
parent: my-parent
---

因此，对于 docs/en/prologue/getting-started/intro.md 中的文件，父级将是 getting-started。

内容

Front Matter 之后的任何内容都是您的内容，用 markdown 编写

---
// Front matter ... 
---

# Introduction

Lorem ipsum dolor ....

就这样！您已经在 Filament 中创建了一个简单的知识库。

访问知识库

在您注册了知识库插件的每个面板中，我们自动在侧边栏的底部注入一个文档按钮。

但我们提供更深层次的集成到您的面板中。

集成到资源或页面

您可能有一个专门针对您每个资源（至少是更复杂的那些）的文档知识库部分。

要将您的资源与文档集成，您只需在资源或页面中实现 HasKnowledgeBase 合同。

这将需要您实现 getDocumentation 方法，其中您只需返回您想要集成的文档页面。您可以选择返回字符串（点分隔的路径在 /docs/{locale}/ 内）或使用辅助函数检索模型

use use Guava\FilamentKnowledgeBase\Contracts\HasKnowledgeBase;

class UserResource extends Resource implements HasKnowledgeBase
{
    // ...
    
    // 
    public static function getDocumentation(): array
    {
        return [
            'users.introduction',
            'users.authentication',
            FilamentKnowledgeBase::model()::find('users.permissions'),
        ];
    }
}

这将渲染一个 帮助菜单 按钮，在顶部导航栏的末尾。

如果您添加了多个文档文件，它将渲染一个下拉菜单，否则 帮助 按钮将直接引用您链接的文档。

在模态中打开文档

从您使用文档页面的任何 livewire 组件（您已渲染帮助菜单），您可以创建链接，通过简单地将此片段添加到链接的 href 属性中，自动在模态中打开文档

#modal-
<documentation-id>

例如

<a href="#modal-users.introduction">Open Introduction</a>

模态链接

为了方便从任何地方访问文档，此插件在 Filament 面板中的任何地方添加了拦截片段链接，以便打开文档页面的模态。

要使用模态链接，只需在您的面板中任何位置添加一个带有格式为 #modal-<文档ID> 的链接，例如 #modal-intro.getting-started 即可。

<a href="#modal-intro.getting-started">Open Introduction</a>

只要存在具有该ID的文档（/docs/en/intro/getting-started.md），它将自动打开包含该文档内容的模态窗口。

您甚至可以将URL与他人共享，它会在打开时自动打开模态窗口！

禁用模态链接

要禁用模态链接，只需在您的面板服务提供商的KnowledgeBasePlugin上调用 disableModalLinks() 即可。

帮助动作

该插件附带了一个简洁的 HelpAction，它可以链接到特定的Markdown文件，甚至是部分Markdown文件。

例如，“什么是slug？”帮助是通过以下方式添加的

use Guava\FilamentKnowledgeBase\Actions\Forms\Components\HelpAction;
->hintAction(HelpAction::forDocumentable('projects.creating-projects.slug')
    ->label('What is a slug?')
    ->slideOver(false)
),

访问文档模型

我们在后台使用 sushi 包来存储文档。这样，它们几乎像常规的 Eloquent模型 一样工作。

使用我们的辅助函数获取模型

要获取模型，只需使用我们的辅助函数 KnowledgeBase::model() 即可。

use \Guava\FilamentKnowledgeBase\KnowledgeBase;

// find specific model
KnowledgeBase::model()::find('<id>');
// query models
KnowledgeBase::model()::query()->where('title', 'Some title');
// etc.

缓存

默认情况下，该包缓存所有Markdown文件以确保用户体验顺畅快捷。如果您看不到您的更改，请确保清除缓存。

php artisan cache:clear

自定义

许多功能都可以在一定程度上进行自定义。

自定义知识库面板

您可以使用以下方式根据喜好自定义知识库面板：

use Guava\FilamentKnowledgeBase\Filament\Panels\KnowledgeBasePanel;

KnowledgeBasePanel::configureUsing(
    fn(KnowledgeBasePanel $panel) => $panel
        // Your options here
);

更改品牌名称

例如，要更改面板默认品牌名称/标题（显示在左上角），您可以这样做：

use Guava\FilamentKnowledgeBase\Filament\Panels\KnowledgeBasePanel;

KnowledgeBasePanel::configureUsing(
    fn(KnowledgeBasePanel $panel) => $panel
        ->brandName('My Docs')
);

在文档文章上使用自定义类

默认情况下，文档文章（Markdown内容渲染的容器）具有 gu-kb-article 类，您可以使用它进行定位和修改。您还可以使用以下方式添加自己的类（们）：

use Guava\FilamentKnowledgeBase\Filament\Panels\KnowledgeBasePanel;

KnowledgeBasePanel::configureUsing(
    fn(KnowledgeBasePanel $panel) => $panel
        ->articleClass('max-w-2xl')
);

禁用默认类

要完全禁用默认样式，您可以使用以下方式：

use Guava\FilamentKnowledgeBase\Filament\Panels\KnowledgeBasePanel;

KnowledgeBasePanel::configureUsing(
    fn(KnowledgeBasePanel $panel) => $panel
        ->disableDefaultClasses()
);

禁用知识库面板按钮

当在启用了知识库插件的面板中时，我们默认在侧边栏底部渲染一个按钮以跳转到知识库面板。如果您喜欢，可以禁用它。

use \Filament\View\PanelsRenderHook;

$plugin->disableKnowledgeBasePanelButton();

禁用返回默认面板按钮

当在知识库面板中时，将渲染一个类似的按钮以返回默认filament面板。您同样可以禁用它。

use Guava\FilamentKnowledgeBase\Filament\Panels\KnowledgeBasePanel;

KnowledgeBasePanel::configureUsing(
    fn(KnowledgeBasePanel $panel) => $panel
        ->disableBackToDefaultPanelButton()
);

自定义帮助菜单/按钮渲染钩子

如果您想在其他位置放置帮助菜单/按钮，可以覆盖渲染钩子。

use \Filament\View\PanelsRenderHook;

$plugin->helpMenuRenderHook(PanelsRenderHook::TOPBAR_START);

锚点

自定义锚点符号

默认情况下，我们使用 # 符号。您可以使用以下方式自定义符号：

use Guava\FilamentKnowledgeBase\Filament\Panels\KnowledgeBasePanel;

KnowledgeBasePanel::configureUsing(
    fn(KnowledgeBasePanel $panel) => $panel
        ->anchorSymbol('¶')
);

禁用锚点

我们在每个标题前渲染一个锚点前缀（#）。要禁用它，您可以这样做：

use Guava\FilamentKnowledgeBase\Filament\Panels\KnowledgeBasePanel;

KnowledgeBasePanel::configureUsing(
    fn(KnowledgeBasePanel $panel) => $panel
        ->disableAnchors()
);

启用模态预览

如果您想以模态预览的方式打开文档而不是立即跳转到完整页面，您可以像这样启用它：

$plugin->modalPreviews();

滑过效果

如果您更喜欢使用滑过效果，您还可以启用它们。

$plugin->slideOverPreviews();

面包屑

禁用面包屑

默认情况下，在每篇文档页面上，顶部都有一个面包屑。如果您愿意，可以禁用它。

use Guava\FilamentKnowledgeBase\Filament\Panels\KnowledgeBasePanel;

KnowledgeBasePanel::configureUsing(
    fn(KnowledgeBasePanel $panel) => $panel
        ->disableBreadcrumbs()
);

在模态预览标题中启用面包屑

在使用模态预览时，默认情况下标题只显示文档页面的标题。

如果您想显示完整的面包屑到文档页面，可以像这样启用它：

$plugin->modalTitleBreadcrumbs();

在新的标签页中打开文档链接

当你打开文档时，默认情况下它将在同一标签页中打开。

要更改此设置，你可以自定义插件

$plugin->openDocumentationInNewTab()

访客访问

默认情况下，面板仅对认证用户可访问。

如果你想使知识库公开可访问，只需按如下配置即可

use Guava\FilamentKnowledgeBase\Filament\Panels\KnowledgeBasePanel;

KnowledgeBasePanel::configureUsing(
    fn(KnowledgeBasePanel $panel) => $panel
        ->guestAccess()
);

Markdown

我们使用CommonMark作为markdown解析器，以及league/commonmark的php实现。请访问它们的相应网站以获取有关如何使用markdown的参考。

我们还为Markdown解析器添加了一些自定义解析器/扩展，如下所述。

标记支持

为了用你的主题主色调标记某些单词，你可以使用以下语法

In this example, ==this text== will be marked.

结果如下，具体取决于你的主色调

表格支持

你可以使用常规markdown语法来渲染与filament表格风格匹配的表格。

| Syntax     |             Description (center)              |     Foo (right) | Bar (left)      |
|------------|:---------------------------------------------:|----------------:|:----------------|
| Header     |                     Title                     |       Something | Else            |
| Paragraphs |  First paragraph. <br><br> Second paragraph.  | First paragraph | First paragraph |

引用支持

使用常规markdown语法进行引用，你可以渲染整洁的横幅，例如

> ⚠️ **Warning:** Make sure that the slug is unique!

语法高亮

我们通过shiki提供语法高亮（服务器上需要NodeJS）

注意：由于额外的安装步骤，语法高亮默认是禁用的。

要启用它，你必须安装npm包 shiki 和 spatie/shiki-php。

选择哪个版本的shiki包取决于你。我 强烈建议使用最新版本，但如果由于与其他包不兼容而遇到问题，你可能需要降级。

请查看以下表格以获取兼容版本。

安装spatie/shiki-php

composer require spatie/shiki-php:"^2.0"

安装shiki

npm install shiki@^1.0

当使用Node版本管理器时

如果你使用Herd或另一个NVM，你很可能需要为你想要的node版本创建符号链接。请按照以下说明操作。

然后你可以使用以下命令启用语法高亮

use Guava\FilamentKnowledgeBase\Filament\Panels\KnowledgeBasePanel;

KnowledgeBasePanel::configureUsing(
    fn(KnowledgeBasePanel $panel) => $panel
        ->syntaxHighlighting()
);

Vite资源支持

只要提供从你的根项目目录的完整路径，你可以使用默认的图像语法来包含vite资源。

![my image](/resources/img/my-image.png)

包含其他文件

我们支持在文件中包含markdown文件。如果你想要组织markdown或显示整个文档的片段作为帮助按钮而不重复markdown文件，这特别有用。

语法如下

@include(prologue.getting-started)

当你想要显示特定组件或字段的帮助按钮，但又不想处理重复信息时，这非常有帮助。

你可以简单地提取你的markdown的部分到更小的markdown文件中，并将它们包含在主文件中。这样，你就可以在你的帮助操作中仅显示部分。

测试

composer test

变更日志

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

贡献

有关详细信息，请参阅贡献指南。

安全漏洞

有关如何报告安全漏洞，请参阅我们的安全策略。

鸣谢

Lukas Frey
所有贡献者
Spatie - 我们的包骨架是Spatie的Package Tools的修改版本
Spatie shiki和markdown包

许可证

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

guava / filament-knowledge-base

维护者

详细信息

README

一个为您的filament面板添加知识库和文档的插件。

展示

支持我们

安装

简介

知识库面板

模态预览

全局搜索

存储

用法

注册插件

确保您有一个自定义filament主题

构建 CSS

创建文档

Markdown

Front Matter

Front Matter 选项

标题

图标

顺序

组

父级

内容

访问知识库

集成到资源或页面

在模态中打开文档

模态链接

禁用模态链接

帮助动作

访问文档模型

使用我们的辅助函数获取模型

缓存

自定义

自定义知识库面板

更改品牌名称

在文档文章上使用自定义类

禁用默认类

禁用知识库面板按钮

禁用返回默认面板按钮

自定义帮助菜单/按钮渲染钩子

目录

禁用目录

更改目录的位置

锚点

自定义锚点符号

禁用锚点

启用模态预览

滑过效果

面包屑

禁用面包屑

在模态预览标题中启用面包屑

在新的标签页中打开文档链接

访客访问

Markdown

标记支持

表格支持

引用支持

语法高亮

安装spatie/shiki-php

安装shiki

当使用Node版本管理器时

Vite资源支持

包含其他文件

测试

变更日志

贡献

安全漏洞

鸣谢

许可证