README

这是一个Laravel Nova管理员面板的工具，允许您创建基于Markdown的应用程序文档；无需离开Nova环境。

兼容性说明

请注意，此插件现在仅支持Laravel Nova v4。如果您正在使用Laravel Nova <= v3，请使用版本 ^3.0。

功能

解析每个Markdown文档并在Nova仪表板中渲染它们
动态页面标题：每个h1标签（# 标题）被设置为页面标题
- 然后使用每个页面标题构建侧边栏，允许在文档中导航。
- 允许嵌套目录
支持YAML解析以进一步自定义页面标题
代码块语法高亮（通过highlight.js）
将正文内容中的本地链接替换为在Nova环境中工作。
支持浏览器亮色和暗色主题。
如果您想自定义登录/授权重定向逻辑，以便在用户未适当认证时自定义用户看到的界面，则允许自定义登录/授权重定向逻辑。

安装

您可以通过Composer安装此包

composer require dniccum/nova-documentation

然后您需要将包的配置和blade视图文件发布到您的应用程序安装中

php artisan vendor:publish --provider="Dniccum\NovaDocumentation\ToolServiceProvider"

最后，您需要在NovaServiceProvider.php中注册该工具

use Dniccum\NovaDocumentation\NovaDocumentation;

...

/**
 * Get the tools that should be listed in the Nova sidebar.
 *
 * @return array
 */
public function tools()
{
    return [
        // other tools
        new NovaDocumentation,
    ];
}

从版本2升级

如果您是从版本2升级到版本3（Laravel Nova 4支持），请确保您的composer.json包含以下版本/引用以包含更新后的版本

"dniccum/nova-documentation": "^3.0"

添加YAML配置

如果您使用vendor:publish命令发布了此包的配置，您需要将以下代码添加到novadocumentation.php配置文件中的数组

'parser' => env('NOVA_DOCUMENTATION_PARSER', 'yaml'),

设置环境变量

如果您计划不重构Markdown文件以不利用新的YAML配置选项，您需要相应地修改配置文件，或者只需设置以下环境变量

NOVA_DOCUMENTATION_PARSER=markdown

删除虚线水平线

如果您在Markdown文件中有任何---水平线并且使用的是yaml解析器，您需要将它们转换为使用***，因为这会导致YAML处理出错。

使用此工具

在发布此工具的所有资产之后，应该在您的resources目录的根目录下的文档目录中放置两个.md（Markdown）文件。
- 如果您想更改此目录，请更改config('novadocumentation.home')配置定义。
- 默认情况下，“主页”入口点是home.md。再次提醒，如果您想更改它，请确保您修改了config('novadocumentation.home')配置。
如果您使用Markdown设置，侧边栏导航使用两个不同的元素构建：文件名和文件内的标题。此标题从每个文件中的第一个# 标题动态获取。

页面YAML配置/自定义

如果您正在使用yaml解析方法，您有可选的能力来自定义侧边栏中每页的构建和显示方式。您可以修改以下属性

标题 - 侧边栏中页面的标题
路径 - 页面的路径/路由/链接。请提供有效的URL
顺序 - 此页面在侧边栏中出现的顺序

将配置添加到您的页面

如果我们想自定义文档中的某个页面，我们需要将以下内容添加到页面顶部

---
title: "Adding Content"
path: content
order: 2
---

# Adding content to your application

...

需要注意的是，包裹配置的---元素。**如果没有这个元素将无法正常工作**。标题应该是相当直观的。路径允许您自定义到达页面的路由。

链接

如果您想在正文内容中链接到侧边栏之外的其他Markdown文件，请确保使用**相对链接**，并且**不要以斜杠开头**，例如/relative。例如，如果您从主页链接到名为认证的子目录文件，您将这样链接

[authentication](authentication/base.md)

该工具将动态替换此链接。

相对链接

如果您想包含指向应用程序或Nova内部其他位置的相对链接，请包含以斜杠（/）开头的前缀链接

[terms and services](/terms-and-services)

其他类型

支持的其他类型链接

mailto (mailto:) 链接
外部http和https链接

路由和添加新页面

当将新文档添加到应用程序架构中，并且如果您的应用程序利用路由缓存时，**请务必相应地清除/重置您的路由缓存**（php artisan route:clear）。

授权重定向

如果需要，您可以指定未认证的用户在尝试访问模块时被重定向到的位置。为此，修改novadocumentation.login_route设置并将其设置为应用程序中的有效路由。

配置

以下配置项可以在novadocumentation.php配置文件中找到。

<?php

return [

    /*
    |--------------------------------------------------------------------------
    | Title
    |--------------------------------------------------------------------------
    |
    | The name/title of this tool that will appear as a page default if no title is provided.
    |
    */

    'title' => 'Documentation',

    /*
    |--------------------------------------------------------------------------
    | Parser
    |--------------------------------------------------------------------------
    |
    | Set the parser that you would like to use to parse your documentation.
    | It is recommended to use the "yaml" parser as it allows for further
    | configuration, but may not be as user friendly to all devs/users.
    |
    | Available parsers: yaml, markdown
    |
    */

    'parser' => env('NOVA_DOCUMENTATION_PARSER', 'yaml'),

    /*
    |--------------------------------------------------------------------------
    | Markdown Flavor
    |--------------------------------------------------------------------------
    |
    | The flavor/style of markdown that will be used. The GitHub flavor is the
    | default as it supports code blocks and other "common" uses.
    |
    | Available flavors: github, atom, gradient, monokai
    |
    */

    'flavor' => 'github',

    /*
    |--------------------------------------------------------------------------
    | Home Page
    |--------------------------------------------------------------------------
    |
    | The markdown document that will be used as the home page and/or entry
    | point. This will be located within the documentation directory that resides
    | within your application's resources directory.
    |
    */

    'home' => 'documentation/home.md',

    /*
    |--------------------------------------------------------------------------
    | Login Route
    |--------------------------------------------------------------------------
    |
    | The route that the user will be redirected to if they are not authenticated.
    | If no route is provided, a 403 error will be returned.
    |
    */

    'login_route' => null,

];

许可

Nova文档工具是免费软件，根据MIT许可协议授权。

dniccum / nova-documentation

维护者

详细信息