README

一个从GitHub仓库创建Markdown文档的Laravel项目包。方便贡献者编辑。

示例图片显示了litstack文档。GitHub仓库位于litstack/litstack.io。

介绍

使用Docdress，您可以将项目/包的文档在几分钟内转换为具有类似Laravel设计的Web界面。

Docdress提供以下功能

类似Laravel的设计
私有仓库的文档
从仓库的子文件夹中获取文档
由Webhook自动更新
在Laravel项目中包含任意数量的仓库
自定义主题
身份验证

设置

通过composer安装 Docdress

composer require aw-studio/docdress

现在发布所需的资源和配置

php artisan vendor:publish --provider="Docdress\DocdressServiceProvider"

您也可以像这样仅发布 config 或 assets

php artisan vendor:publish --tag="docdress:assets"
php artisan vendor:publish --tag="docdress:config"

将仓库添加到配置

将所需的仓库添加到 docdress 配置中。

'repos' => [
    'my/repo' => [
        //
    ],
],

克隆仓库

配置仓库后，您必须使用 docdress:clone 命令克隆它

php artisan docdress:clone "my/repo"

结构

Readme.md

索引作为嵌套列表在 readme.md 中构建。它位于 ## Index 之下。因此，您的 readme.md 可能如下所示

# My Package

Hello World.

## Index

-   ## Getting Started
    -   [Introduction](introduction.md)
    -   [Installation](installation.md)
-   ## Foo
    -   [Bar](subfolder/bar.md)

配置

Docdress 可以在单个Laravel项目中为任意数量的仓库编写文档。每个仓库都在 docdress.repos 中配置，如下所示

'repos' => [
    'my/repo' => [
        // ...
    ],
],

可以为仓库配置以下属性

route_prefix - 可访问文档的路由前缀。
default_page - 默认页面
versions - 包含应可在文档中使用的分支的数组。
default_version - 当前版本。
subfolder - 文档的子文件夹。
theme - 应用于此仓库的主题。默认值：default。
access_token - 私有仓库的个人访问令牌。
webhook_token - 允许在更改后拉取仓库的Webhook令牌。

以下属性将在下面进行更详细的讨论

版本

每个版本代表一个分支。将 default_version 设置为您的默认分支。版本指定为分支名称和标题，如下所示

'repos' => [

    'my/repo' => [
        // ...
        'default_version' => 'master',
        'versions'        => [
            'master' => 'Master',
            '1.0'    => '1.0'
        ]'
    ],

],

私有仓库

私有仓库需要具有读取权限的个人访问令牌。

'repos' => [

    'my/repo' => [
        // ...
        'access_token' => env('GITHUB_ACCESS_TOKEN', null)
    ],

],

子文件夹

您可以在对应仓库的子文件夹中拥有项目或包的文档。如果配置中指定了 subfolder，则仅克隆并显示此文件夹。

'repos' => [

    'my/repo' => [
        // ...
        'subfolder' => 'docs'
    ],

],

Webhook

如果您希望每次推送时自动更新最新版本，则必须设置一个URL为 _docdress/update 的Webhook。

此外，必须将 Content-Type 设置为 application/json。

并且需要指定从您的配置中获取的 token。

'repos' => [

    'my/repo' => [
        // ...

        'webhook_token' => env('GITHUB_WEBHOOK_TOKEN', null),
    ],

],

Algolia

可以使用 Algolia Docsearch 来搜索您的文档。您只需要指定相应仓库的 应用程序密钥。

'repos' => [

    'my/repo' => [
        // ...

        'algolia_app_key' => env('ALGOLIA_APP_KEY', null),
    ],

],

授权

您可以在 AuthServiceProvider 的 boot 方法中为仓库创建一个门来管理对文档的访问。

use Docdress\Docdress;

public function boot()
{
    $this->registerPolicies();

    Docdress::gate('my/repo', function ($user) {
        return $user->is_admin;
    });
}

警报

您可以在 vuepress 中像自定义块一样显示警报。可用的警报类型有 tip、warning、danger。

::: tip

Hello World!

:::

::: warning

Hello World!

:::

::: danger

Hello World!

:::

alert-tip alert-warning alert-danger

搜索组件

通过使用 x-dd-search-input 组件。您可以将 algolia 搜索输入放置在您的 blade 视图中。该组件需要要搜索的 repo 和所需的版本。

<x-dd-search-input repo="my/repo" version="1.0" />

测试

通过 composer 执行测试。

composer test

aw-studio / docdress

维护者

详细信息