README

本WordPress插件可自动为当前文章生成目录。

注意！ 此插件正在公开开发中，最终目标是使其在 Growella 上提供动态目录功能，并在 WordPress.org 上发布。但请注意，该插件仍在积极开发中，可能不够稳定，不适合生产环境使用！

使用方法

将 [toc] 短代码插入到您希望出现目录的帖子内容中。插件将自动为帖子内容中的每个标题生成ID，然后在您放置短代码的地方构建列表。

例如，假设您想在引言段落后嵌入目录。您可以通过移动短代码来完全控制位置

<h2>Introduction</h2>
...

[toc]

<h2>First topic</h2>
...

<h2>Second topic</h2>
...

对于该示例，生成的目录将如下所示

引言

第一主题

第二主题

短代码选项

[toc] 短代码有几个可用参数，可以用于控制每个帖子上的生成的目录。如果您希望在全球范围内更改默认设置，请参阅 growella_table_of_contents_shortcode_defaults 过滤器。

class

应用于目录的额外HTML类名（空格分隔）。默认为空字符串。

为了便于样式化，渲染的目录将始终具有 .growella-table-of-contents。

示例

将 "sticky" 和 "special-nav" 类添加到渲染的目录中。

[toc class="sticky special-nav"]

depth

注意： 此参数尚未实现。

控制生成的目录嵌套的深度

-1: 显示找到的所有标题（基于 $tags 参数）的平面列表。这是默认行为。
0: 仅显示顶级标题。例如，如果一个H2级别的标题下有一个H3级别的（或更高）标题，则目录中仅显示H2的链接。
$n: 在目录中将子标题嵌套到列表的 $n 级别。

title

出现在目录顶部的标题。默认值为 "目录"。传递空字符串（或任何其他 "false-y" 值）将防止创建此标题。

示例

将标题更改为 "本文内容："

[toc title="In this article:"]

或者，如果您希望不显示标题，传递空字符串

[toc title=""]

可用过滤器

Growella Table of Contents公开了几个过滤器，用于与WordPress插件API一起使用。

growella_table_of_contents_shortcode_defaults

修改Growella目录[toc]短代码的默认设置。

数组 $defaults: 默认短代码属性。

此过滤器非常适合如果您想覆盖全局默认设置以更好地适应您的主题，同时允许编辑人员在需要时仍然可以在每篇文章的基础上覆盖新默认设置。

示例

将默认标题更改为"本文内容"。

/**
 * Override default settings for Growella Table of Contents' [toc] shortcode.
 *
 * @param array $defaults Default shortcode attributes.
 * @return array The modified $defaults.
 */
function mytheme_override_toc_defaults( $defaults ) {
	$defaults['title'] = 'In this article';

	return $defaults;
}
add_filter( 'growella_table_of_contents_shortcode_defaults', 'mytheme_override_toc_defaults' );

growella_table_of_contents_render_shortcode

在返回渲染的短代码输出之前过滤Growella目录。

字符串 $output: 渲染的目录。
数组 $atts: 用于构建目录的短代码属性。
数组 $links: 用于构建目录的链接。

growella_table_of_contents_link_anchor_text

在将锚文本放入链接之前过滤目录链接的锚文本。

字符串 $anchor: 构建链接时要使用的锚文本。
DOMElement $element: 表示DOM节点的DOMElement对象。

示例

如果标题超过80个字符，则截断链接并附加省略号。

/**
 * Truncate anchor text in the table of contents to 80 characters.
 *
 * @param string $anchor  The anchor text to be used when building the link.
 * @return string The filtered $anchor text.
 */
function mytheme_truncate_toc_links( $anchor ) {
	if ( 80 < strlen( $anchor ) ) {
		$anchor = substr( $anchor, 0, 80 ) . '&hellip;';
	}

	return $anchor;
}
add_filter( 'growella_table_of_contents_link_anchor_text', 'mytheme_truncate_toc_links' );

growella / table-of-contents

维护者

详细信息