README

此包允许您在Symfony项目中使用Markdown创建丰富的子页面。页面存储在文件缓存中，并从外部目录获取，例如Git子模块。

您可以使用此包创建帮助部分、信息维基或其他任何类型的子页面，这些页面不应用于硬编码到您的Symfony代码库中。

功能

• 从Markdown文件获取页面
• 页面元数据存储在单独的YAML文件中
• 支持多语言，无locale代码限制
• 自定义解析、存储和获取页面的实现

要求

• Symfony 5.3+
• PHP 8

安装

composer require gigadrive/markdown-wiki-bundle

配置

此包使用标准的Symfony包配置进行配置。

# config/packages/markdown_wiki_bundle.yaml
markdown_wiki_bundle:
    source_directory: "%kernel.project_dir%/example-wiki/pages/"

• source_directory定义了包含源文件的目录路径。这些文件构成了您的维基的内容和数据。为了最佳实践，请使用Git子模块。

使用

安装和配置包后，您需要为Markdown文件创建一个文件结构。您可以在这里找到一个示例维基以获取帮助。

维基目录中的文件结构保持简单。

• 每个文件夹代表页面路径的一个级别。
• 每个页面的文件夹需要包含两个文件，一个名为meta.yaml，另一个名为content.md。如果您想支持多种语言，请根据您的语言代码命名这些文件。例如，对于英文页面，它们分别命名为en.md和en.yaml
• meta.yaml文件需要包含以下键：title 页面标题 description 页面描述 任何其他键将作为“自定义属性”传递。如果您需要任何其他页面数据，请在此处保存。

示例：如果您想创建一个路径为/account/creation的页面，您需要一个路径为/account/creation的文件夹。在该文件夹中，您需要创建一个名为meta.yaml的文件和一个名为content.md的文件。第一个包含关于您页面的元数据，第二个包含您的实际页面内容。

服务页面

您可以在这里找到一个服务页面的示例控制器。

自定义解析器

MarkdownWikiBundle使用Parsedown构建，这是一个用于用PHP解析Markdown的免费开源库。此包将Parsedown注册为服务（MarkdownWikiParser）并用于解析。要覆盖解析行为，请执行以下操作

首先，创建自己的解析器实现

namespace App\Service;

use Gigadrive\Bundle\MarkdownWikiBundle\Service\MarkdownWikiParser;

class ExampleParser extends MarkdownWikiParser {
    // TODO: Extend Parsedown
}

现在您有一个扩展Parsedown的类。请参考Parsedown的文档，以扩展新服务中的解析行为。完成之后，通过覆盖Symfony容器中的实现来注册您的新解析器。

# config/services.yaml
services:
    app.parser:
        class: App\Service\ExampleParser

    markdownwiki.parser:
        alias: app.parser

自定义存储

默认情况下，页面在 Symfony 文件缓存中进行缓存。可以通过 MarkdownWikiStorageInterface 覆盖此行为。使用此接口，您可以创建自己的存储行为并将缓存的页面保存到 Redis、Doctrine 或您需要的任何地方。

为确保该组件使用您的存储而不是默认存储，需要覆盖 markdownwiki.storage 容器键。

# config/services.yaml
services:
    markdownwiki.storage.example:
        class: App\Service\YourStorageImplementation

    markdownwiki.storage:
        alias: markdownwiki.storage.example

示例 Wiki

此组件是为 MCSkinHistory 帮助部分创建的。您可以在 这里 找到它的源代码，以帮助您了解此类 Wiki 的预期结构。

重建缓存

当 Wiki 页面有更新时，组件的内部缓存需要重建。这可以通过运行随组件提供的以下控制台命令完成：

php bin/console wiki:rebuild-storage-cache

也可以通过 MarkdownWikiStorageService 以编程方式重建缓存。

use Gigadrive\Bundle\MarkdownWikiBundle\Service\MarkdownWikiStorageService;

class ExampleService {
    public function __construct(
        protected MarkdownWikiStorageService $storageService
    ) {
    }

    public function rebuildCaches() {
        $this->storageService->rebuildStorageCache();
    }
}

测试

此组件使用 PHPUnit 作为测试框架。

在开发此组件时，使用以下命令测试其功能：

git submodule update --init --recursive
composer install
php ./vendor/bin/phpunit

版权和许可证

本程序由 Mehdi Baaboura 开发并由 Gigadrive UG 发布，遵循 MIT 许可证。更多信息请点击 这里。