README

基于 PHP 的 Markdown 文件查看器，可以带有代码高亮和导航功能来查看文件。

它被设计成用于查看基于 Markdown 的文档文件，使用起来简单快捷。布局基于 Bootstrap 5，无需任何额外配置。

要求

• PHP7.4+

特性

• 使用文档标题自动跳转导航。
• 轻松切换到可用的文档。
• 语法高亮代码块。
• 浅色和深色模式。
• 额外支持“1)”样式的有序列表。

安装

此包设计为作为文档项目的依赖项使用：将其放在 web 服务器的一个文件夹中，指向一些 Markdown 文件，它将显示这些文件。

1. 在您的网站根目录中创建一个文件夹，用于提供文档。
2. 在该文件夹中创建一个 composer 项目。
3. 要求包：composer require mistralys/markdown-viewer。
4. 创建一个 PHP 文件（index.php），作为文档的端点。
5. 将以下代码粘贴到文件中
6. 编辑您希望查看的文件列表。
7. 将浏览器指向该文件。

<?php

declare(strict_types=1);

use Mistralys\MarkdownViewer\DocsManager;
use Mistralys\MarkdownViewer\DocsViewer;

if(!file_exists(__DIR__.'/vendor/autoload.php')) {
    die('Please run <code>composer install</code> first.');
}

require_once __DIR__.'/vendor/autoload.php';

$manager = new DocsManager();

// Add all the files you wish to view here, along with
// a title that will be shown in the UI.
$manager->addFile('Title of the file', '/path/to/documentation.md');

// The viewer needs to know the URL to the vendor/ folder, relative
// to the script. This is needed to load the clientside dependencies,
// like jQuery and Bootstrap.
(new DocsViewer($manager, '/url/to/vendor'))
    ->setTitle('Documentation')
    ->display();

添加单个文件

可以使用 addFile() 添加单个文件。这允许指定文件在 UI 中显示的名称。

use Mistralys\MarkdownViewer\DocsManager;

$manager = new DocsManager();

// Add a single folder, non-recursive.
$manager->addFile('Name of the file', '/path/to/file.md');

添加文件夹

要添加多个文件，请使用 addFolder() 方法

use Mistralys\MarkdownViewer\DocsManager;

$manager = new DocsManager();

// Add a single folder, non-recursive.
$manager->addFolder('/path/to/files');

// Add a folder and all its subfolders
$manager->addFolder('/path/to/files', true);

默认情况下，所有具有 md 扩展名的文件都将被添加。可以使用第三个参数指定不同的扩展名

use Mistralys\MarkdownViewer\DocsManager;

$manager = new DocsManager();

// Add all TXT files from a single folder, non-recursive.
$manager->addFolder('/path/to/files', false, 'txt');

注意：以这种方式添加文件意味着您不能指定文件 ID（请参阅“一致的文件永久链接”）。请确保这符合您的使用情况。

一致的文件永久链接

默认情况下，查看器将为每个文件创建一个基于磁盘上绝对路径的 ID。这意味着如果文件在某个时间点被移动，或者如果查看器在不同的系统上使用，ID 将会改变。共享永久链接可能会导致链接在某些时间点被破坏。

为了避免这个问题，在添加单个文件时手动指定唯一的文件 ID

use Mistralys\MarkdownViewer\DocsManager;

$manager = new DocsManager();

$manager->addFile(
    'Name of the file', 
    '/path/to/file.md',
    '(Unique file ID)'
);

ID 可以是任何字符串；查看器使用它来创建 UI 中用于识别文件的哈希。这样，永久链接总是会保持一致。

深色模式

要启用深色模式，只需使用 makeDarkMode()

use Mistralys\MarkdownViewer\DocsViewer;
use Mistralys\MarkdownViewer\DocsManager;

$manager = new DocsManager();

// Configure the files

(new DocsViewer($manager, '/url/to/vendor'))
    ->setTitle('Documentation')
    ->makeDarkMode()
    ->display();

查看示例

捆绑的示例与上面的示例构建方式完全相同，将显示此 README.md 文件。要运行它，请按照以下步骤操作

1. 将存储库克隆到 web 服务器的文档根目录
2. 在包文件夹中运行 composer install 以安装依赖项
3. 将浏览器指向包文件夹的 example.php 文件

设置选项

有关解析 Markdown 文件的选项的所有内容都由 DocsConfig 类处理。您可以可选地传递一个配置实例给管理器以自定义设置

use Mistralys\MarkdownViewer\DocsManager;
use Mistralys\MarkdownViewer\DocsConfig;

$config = (new DocsConfig())
    ->addIncludePath(__DIR__.'/documentation/includes')
    ->addIncludeExtension('php');

$manager = (new DocsManager($config))
    ->addFile('Package readme', 'README.md');

包含外部文件

包含命令

{include-file} 命令允许您将外部文件的内容导入到文档中。这对于代码示例特别有用，因为它允许您将它们与主文档分开维护。

如果通过 example.php 查看，以下代码示例将动态加载，例如

{include-file: test-php-highlight.php}

命令看起来像这样

\{include-file: test-php-highlight.php\}

注意：过度使用include很常见。请记住，Markdown文件是设计为直接阅读的。过度拆分它们会导致在没有UI的情况下无法阅读。在合理的地方使用它们，比如大的代码示例。

设置允许的路径

默认情况下，include命令是禁止的，除非已配置include文件夹

use Mistralys\MarkdownViewer\DocsConfig;

$config = (new DocsConfig())
    ->addIncludePath('/documentation/includes');

{include-file}命令中的路径相对于配置的include路径。可以添加多个文件夹，并且都会被搜索。然后使用第一个匹配的文件名。

设置允许的扩展名

默认情况下，仅允许包含md和txt文件。可以轻松添加其他扩展名

use Mistralys\MarkdownViewer\DocsConfig;

$config = (new DocsConfig())
    ->addIncludeExtension('php');

也可以一次性添加多个扩展名

use Mistralys\MarkdownViewer\DocsConfig;

$extensions = array(
    'php',
    'js',
    'css'
);

$config = (new DocsConfig())
    ->addIncludeExtensions($extensions);

限制文件大小

为了避免包含大文件，默认情况下只能包含6Kb以下的文件。这可以通过配置类进行调整

use Mistralys\MarkdownViewer\DocsConfig;

// Allow files up to 12Kb (12.000 bytes)
$config = (new DocsConfig())
    ->setMaxIncludeSize(12000);

过滤include文件内容

过滤器允许在Markdown渲染器渲染之前对包含的文件进行预处理。可以过滤整个文件内容，以准备渲染。

示例过滤器类

<?php

declare(strict_types=1);

use AppUtils\FileHelper\FileInfo;
use Mistralys\MarkdownViewer\DocFile;
use Mistralys\MarkdownViewer\DocsConfig;
use Mistralys\MarkdownViewer\Parser\BaseIncludeFilter;

class ExampleIncludeFilter extends BaseIncludeFilter
{
    public function getExtensions(): array
    {
        return array('example');
    }
    
    public function isValidFor(DocFile $sourceFile, DocsConfig $config, FileInfo $includeFile): bool
    {
        return true;
    }

    public function filter(string $content): string
    {
        return str_replace('EXAMPLE', '**EXAMPLE**', $content);
    }
}

此过滤器确保文本中所有出现的EXAMPLE都格式化为粗体文本。

添加过滤器

添加过滤器非常简单。只需将过滤器实例添加到配置中，它将自动应用。

<?php
use Mistralys\MarkdownViewer\DocsConfig;

$config = (new DocsConfig())
    ->addIncludeFilter(new ExampleIncludeFilter());

仅过滤特定文件

默认情况下，过滤器应用于所有匹配过滤器文件扩展名（s）的文件。然而，如果扩展名匹配，只有当isValidFor()方法返回true时，才会应用过滤器。这使得可以使用提供的文件和配置信息来决定是否过滤内容。

以下示例将过滤限制为在/path/to/target/folder文件夹中找到的包含文件，或其任何子文件夹。

<?php

declare(strict_types=1);

use AppUtils\FileHelper\FileInfo;
use Mistralys\MarkdownViewer\DocFile;
use Mistralys\MarkdownViewer\DocsConfig;
use Mistralys\MarkdownViewer\Parser\BaseIncludeFilter;

class ExampleIncludeFilter extends BaseIncludeFilter
{
    public function isValidFor(DocFile $sourceFile, DocsConfig $config, FileInfo $includeFile): bool
    {
        return $includeFile->isWithinPath('/path/to/target/folder');
    }
}