README

WP帮助文档插件允许您将WordPress主题或插件的帮助文档直接集成到WordPress管理界面。

文档使用Markdown编写，具有特殊扩展功能，允许链接到其他Markdown文件、链接到管理页面、视频嵌入、显示目录和其他功能。

WP帮助文档还集成了搜索功能。

有关将此文档插件与您的插件或主题集成的示例，请查看这些示例

安装

通过Composer安装

composer require ilab/ilab-docs

或者，通过WordPress插件仓库安装。

或者，从发布页面下载zip文件并手动安装。

编写文档

文档位置

如果您正在为您的主题编写文档，您需要将文档放置在主题根目录下的名为docs的目录中，插件将自动找到它。

对于插件文档或docs目录之外的目录，您必须告诉文档插件从哪里加载其文档。您可以通过ilab-docs-config过滤器来完成此操作。

add_filter('ilab-docs-config', function($docsConfig){
	$docsConfig[] = [
		'title' => 'My Plugin',
		'dir' => dirname(__FILE__).'/docs/',
		'url' => plugin_dir_url( __FILE__ ).'docs/'
	];

    return $docsConfig;
}, 10000, 1);

此过滤器应添加到您的插件的主/入口PHP文件或您的主题的functions.php文件中。

目录结构

您的docs文件夹的基本目录结构应如下所示

images/
config.json
index.md
docs.css

文件夹images包含文档中包含的任何图像。文件config.json包含文档的配置和目录。文件index.md是文档的初始页面。docs.css是您希望包含在文档中的任何附加CSS。

此外，您还将为要包含的每个文档页面添加额外的Markdown文件。

配置

每个文档集都需要一个配置文件。配置文件是一个简单的JSON文件，它提供了文档的标题、要在各种菜单区域显示的文档名称、标志和目录。

基本的配置文件如下所示

{
  "title": "Documentation Title",
  "menu": "Documentation",
  "toolbar": "Docs",
  "logo": {
    "src": "images/doc-logo.svg",
    "width": 130,
    "height": 29
  },
  "toc": [
    {
      "title": "CMS Overview",
      "src": "index"
    },
    {
      "title": "Custom Content Types",
      "src": "content-types",
      "children": [
        {
          "title": "Managing Bios",
          "src": "content-types/bios"
        },
        {
          "title": "Managing Case Studies",
          "src": "content-types/case-studies"
        },
        {
          "title": "Managing News",
          "src": "content-types/news"
        }
      ]
    }
  ]
}

基础

标题

这是您的文档标题，它将显示在文档的页眉以及页面标题中。

菜单

这是文档在WordPress管理侧边栏中显示时的标题。

标志

这是文档中使用的标志。它可以任何有效的图像类型，并且应位于您的docs目录的images/文件夹中。

工具栏

这是在WordPress管理工具栏中显示的标题名称。

独立

如果您正在编写插件文档，将此标志设置为true将使您的插件文档成为顶级菜单项，而不是被分组在插件文档管理菜单中。除非您的插件是必需使用或是一个具有大量文档的主要插件，否则不应这样做。

主题文档始终是顶级菜单项。

Markdown 扩展

WP 帮助文档插件通过几种方式扩展了markdown，以方便编写交叉引用文档。

链接

您可以使用标准的markdown链接链接到文档中的其他页面

[Other Documentation](other-documentation.md)

插件会解析这些链接，并用实际显示页面的链接替换它们。

这些链接始终相对于您的文档目录。

管理员链接

有时您可能想链接到WordPress管理的一些部分。您可以使用admin:前缀来做到这一点，如下所示

The menus on the site are editable via WordPress's built-in [menu editor](admin:nav-menus.php).

本地图片

由于您的文档将显示在与其存储位置无直接关系的页面上，常规的markdown图片将无法使用。因此，要包含相对于您的文档目录的图片，您只需简单地写入它，而不使用正斜杠

![Image Name](images/image.png)

插件会自动将其映射到您的images/目录中的图片，无论文档实际上在哪里显示。

视频嵌入

要嵌入视频内容，请使用@符号，如下所示

@[Video Name](https://www.youtube.com/watch?v=dQw4w9WgXcQ)

目前，支持youtube、vimeo和dailymotion的视频。

表格标题样式

您可以使用{}指定表格标题的CSS类

#### Content Properties
{callout} | Property{property} | Description{description}
----------|--------------------|-------------------------
![#1](images/icon-callout-1.png)|**Title**|The title of the callout panel.
![#2](images/icon-callout-2.png)|**Subtitle**|The subtitle of the callout panel.
![#3](images/icon-callout-3.png)|**Link**|The link to display in the callout's header, optional.  See [Link Properties](pages/content-blocks/link.md) for configuring links.

在上面的示例中，第一列没有显示任何文本，而是使用了一个名为callout的CSS类。属性列使用名为property的CSS类，而描述列使用名为description的CSS类。

这是为了提供更多控制表格列宽的能力。例如，这些类的实际CSS看起来如下

.ilab-docs-body .property {
    width: 84px;
    min-width: 84px;
}
.ilab-docs-body .description {
    width: 100%;
}

.ilab-docs-body .callout {
    width: 32px;
    min-width: 32px;
    max-width: 32px;
}

CSS包含在您的docs目录中的docs.css文件中。

搜索

WP 帮助文档通过teamtnt/tntsearch包支持文档搜索。但为了启用搜索，您首先需要生成一个搜索索引。您可以从命令行使用wp-cli来完成此操作。打开终端并切换到您的文档目录。输入以下内容

wp docs index

然后，将在您的文档目录的根目录中生成一个名为docs.index的文件。这就是启用搜索所需的所有操作！

注意：您需要安装PHP SQLite3扩展才能使搜索功能正常工作。

ilab / ilab-docs

维护者

详细信息