docs(highlight-targeted-heading): added documentations

docs/pages/en/integrations/vitepress-plugin-highlight-targeted-heading/index.md

@@ -1,5 +1,112 @@
 # Blinking highlight targeted heading
 
-::: warning 🚧 Constructing
-Nice to meet you! But sorry, this page is still under construction. If you don’t find the information you are interested in, you can first find the content you are interested in in the navigation in the sidebar to start reading.
+## Demo
+
+<video controls muted>
+  <source src="./assets/demo-video-1.en.mov">
+</video>
+
+When we click on the outline on the right to navigate, there will be a yellow blinking block flashing around the targeted title element.
+
+## Why
+
+Today's documentation websites will support reading the [Hash ID passed in the URL](https://developer.mozilla.org/en-US/docs/Web/API/Location/hash) and then scrolling the page until the Hash ID selected element appears or appears at the top position. This function is usually triggered by the user clicking the anchor icon on the left or right of the title, or clicking the interactive and selectable outline list on the right.
+
+However, most of the targeted title elements of the documentation website will not highlight and indicate where the currently highlighted title line is after clicking.
+
+::: info What is the targeted title? How does this feature work?
+
+When you click on the link in the outline on the right or directly click the link button on the left of the title, pay attention to the changes in the address bar.
+
+You will find that there is a `#` symbol in the URL, followed by an ID, which is the ID of the targeted title.
+
+The ID of the targeted title mentioned here is actually the ID of the HTML element, so in theory, not only can the framework and the browser be required to scroll the title element into the viewport, but also other valid elements with matching HTML IDs.
+
+This kind of element can be found by pressing <kbd>F12</kbd> to open the developer tool, and then enter
+
+```js
+document.querySelector('#why')
+```
+
+in the console to find it. This code will return an HTML element, which is what we call the "targeted title".
+
+:::
+
+Why do you need to highlight?
+
+1. When user clicks one of the titles, the page scrolls to the position where the title is located, but the user does not know where the current title is due to the fact that there are several titles on the screen.
+2. When user clocks one of the titles, the page is already at the bottom of the page, and the user cannot learn how to find the title by a fixed "look at the top of the viewport to find and locate the title" repeatable behavior pattern. Such scenario is even more critical when several titles appear at the end of the document.
+
+At this time, being able to indicate and highlight the title that cannot be noticed is a very important thing, and this integration was born because of this.
+
+## How to install and configure
+
+### Install
+
+You can install `@nolebase/vitepress-highlight-targeted-heading` to the dependencies of the VitePress project with the following command:
+
+::: code-group
+
+```shell [pnpm]
+pnpm add @nolebase/vitepress-highlight-targeted-heading
+```
+
+```shell [npm]
+npm install @nolebase/vitepress-highlight-targeted-heading
+```
+
+```shell [yarn]
+yarn add @nolebase/vitepress-highlight-targeted-heading
+```
+
+:::
+
+### Configure for VitePress
+
+In VitePress's [**theme configuration file**](https://vitepress.dev/reference/default-theme-config#default-theme-config) (note that it's not a **configuration file**, it's usually located at `docs/.vitepress/theme/index.ts`, file paths and extensions may be vary), import `@nolebase/vitepress-plugin-enhanced-readabilities` import and add it to the `Layout` extension:
+
+<!--@include: @/pages/en/snippets/details-colored-diff.md-->
+
+::: code-group
+
+```typescript [docs/.vitepress/theme/index.ts]
+import { h } from 'vue'
+import DefaultTheme from 'vitepress/theme'
+import type { Theme as ThemeConfig } from 'vitepress'
+import {  // [!code ++]
+  NolebaseHighlightTargetedHeading,  // [!code ++]
+} from '@nolebase/vitepress-plugin-highlight-targeted-heading' // [!code ++]
+
+import '@nolebase/vitepress-plugin-highlight-targeted-heading/dist/style.css' // [!code ++]*
+
+export const Theme: ThemeConfig = {
+  extends: DefaultTheme,
+  Layout: () => {
+    return h(DefaultTheme.Layout, null, {
+      // other configurations...
+      'layout-top': () => [ // [!code ++]
+        h(NolebaseHighlightTargetedHeading), // [!code ++]
+      ], // [!code ++]
+    })
+  },
+  enhanceApp() {
+    // other configurations...
+  },
+}
+
+export default Theme
+```
+
 :::
+
+That's it, it is usable now 🎉.
+
+## How to use
+
+Now build or open the VitePress development server again, you will be able to observe that as long as there is an element with a corresponding ID in the `#` in the URL, the following situations will take effect:
+
+- Click the link button on the left of the title directly
+- Click the link in the outline on the right directly
+- The URL containing `#` is loaded for the first time
+
+That's all, happy writing!

docs/pages/zh-CN/integrations/vitepress-plugin-enhanced-readabilities/index.md

@@ -66,7 +66,7 @@ yarn add @nolebase/vitepress-plugin-enhanced-readabilities
 
 #### 添加 Vite 相关的配置
 
-首先，请在你的 VitePress [**核心配置文件**](https://vitepress.dev/reference/site-config#config-resolution) 中（注意不是**主题配置文件**，通常为`docs/.vitepress/config.ts`，文件路径和拓展名也许会有区别）的根字段中添加 [Vite](https://vitejs.dev) 与 [SSR 服务端渲染相关](https://cn.vitejs.dev/config/ssr-options.html#ssr-external) 的配置。
+首先，请在你的 VitePress [**核心配置文件**](https://vitepress.dev/reference/site-config#config-resolution) 中（注意不是**主题配置文件**，通常为 `docs/.vitepress/config.ts`，文件路径和拓展名也许会有区别）的根字段中添加 [Vite](https://vitejs.dev) 与 [SSR 服务端渲染相关](https://cn.vitejs.dev/config/ssr-options.html#ssr-external) 的配置。
 
 将阅读增强的插件包 `@nolebase/vitepress-plugin-enhanced-readabilities` 添加到需要 VitePress 底层的 Vite 帮忙处理的依赖：
 

docs/pages/zh-CN/integrations/vitepress-plugin-highlight-targeted-heading/index.md

@@ -1,5 +1,113 @@
 # 闪烁高亮当前的目标标题
 
-::: warning 🚧 施工中
-很高兴见到你！但很抱歉，这个页面还在施工中，如果没有找到你感兴趣的信息，你可以先在侧边栏的导航中寻找你感兴趣的内容来开始阅读
+## 效果演示
+
+<video controls muted>
+  <source src="./assets/demo-video-1.zh-CN.mov">
+</video>
+
+当我们点击右侧的大纲进行导览的时候会有黄色的闪烁块在标题元素周围闪烁。
+
+## 为什么
+
+当今的文档网站都会支持读取 [URL 中传递的 Hash ID](https://developer.mozilla.org/en-US/docs/Web/API/Location/hash) 然后滚动页面直至 Hash ID 选中的元素出现或出现在靠上的位置上，这个功能通常以用户点击标题左侧或右侧的 anchor 图标，或者是点击了右侧可交互和可选择的大纲列表中的元素为触发条件。
+
+然而绝大多数的文档网站的目标标题都不会在点击后高亮和指示当前高亮的标题行在哪里。
+
+::: info 目标标题是什么？这样的功能是如何工作的？
+
+当点击右侧大纲内的链接或者直接点击标题左侧的链接按钮的时候，注意观察地址栏中的变化。
+
+你会发现 URL 中会出现一个 `#` 符号，后面跟着一个 ID，这个 ID 就是目标标题的 ID。
+
+这里说的目标标题的 ID 其实就是 HTML 元素的 ID，所以理论上不光是可以要求框架和浏览器配合着去滚动标题元素到视窗内，也可以是其他有效的带有匹配得上 HTML ID 的元素。
+
+这样的元素可以通过按下 <kbd>F12</kbd> 打开开发者工具，然后在控制台中输入
+
+```js
+document.querySelector('#为什么')
+```
+
+来查找到，这段代码将会返回一个 HTML 元素，这个元素就是我们说的「目标标题」。
+
 :::
+
+为什么会需要高亮呢？
+
+1. 一个屏幕中出现了好几个标题的时候，用户点击了其中一个标题，然后页面滚动到了标题所在的位置，但是用户并不知道当前的标题在哪里，这个时候用户就需要自行寻找标题，这个过程是非常不友好的，因为用户需要重新阅读视口内的内容并自行寻找到他们希望寻找的标题。
+2. 对于文档末尾有多个标题的时候，点击右侧的大纲将不会发生页面的滚动动画，用户，作为读者自然也就无法通过一个固定的「看窗口顶部的标题来寻找和定位标题」的可重复行为模式来学习如何寻找标题。
+
+这个时候能够指示和高亮察觉不到的标题高亮就是一件非常重要的事情，这个插件就是因此而诞生的。
+
+## 怎么安装和配置
+
+### 安装
+
+你可以通过下面的命令将 `@nolebase/vitepress-highlight-targeted-heading` 安装到 VitePress 项目的依赖中：
+
+::: code-group
+
+```shell [pnpm]
+pnpm add @nolebase/vitepress-highlight-targeted-heading
+```
+
+```shell [npm]
+npm install @nolebase/vitepress-highlight-targeted-heading
+```
+
+```shell [yarn]
+yarn add @nolebase/vitepress-highlight-targeted-heading
+```
+
+:::
+
+### 为 VitePress 配置
+
+在 VitePress 的[**主题配置文件**](https://vitepress.dev/reference/default-theme-config#default-theme-config)中（注意不是**配置文件**，通常为 `docs/.vitepress/theme/index.ts`，文件路径和拓展名也许会有区别），将 `@nolebase/vitepress-highlight-targeted-heading` 导入，并且将其添加到 `Layout` 的拓展中：
+
+<!--@include: @/pages/zh-CN/snippets/details-colored-diff.md-->
+
+::: code-group
+
+```typescript [docs/.vitepress/theme/index.ts]
+
+import { h } from 'vue'
+import DefaultTheme from 'vitepress/theme'
+import type { Theme as ThemeConfig } from 'vitepress'
+import {  // [!code ++]
+  NolebaseHighlightTargetedHeading,  // [!code ++]
+} from '@nolebase/vitepress-plugin-highlight-targeted-heading' // [!code ++]
+
+import '@nolebase/vitepress-plugin-highlight-targeted-heading/dist/style.css' // [!code ++]*
+
+export const Theme: ThemeConfig = {
+  extends: DefaultTheme,
+  Layout: () => {
+​    return h(DefaultTheme.Layout, null, {
+      // 其他的配置...
+      'layout-top': () => [ // [!code ++]
+        h(NolebaseHighlightTargetedHeading), // [!code ++]
+      ], // [!code ++]
+​    })
+  },
+  enhanceApp() {
+​    // 其他的配置...
+  },
+}
+
+export default Theme
+```
+
+:::
+
+就是这么多了，接下来已经可以使用了！
+
+## 如何使用
+
+现在再次构建或者打开 VitePress 的开发服务器，你将可以观测到，只要是 URL 中的 `#` 有对应的 ID 的元素的时候，下面的情况都会生效：
+
+- 直接点击标题左侧的链接按钮
+- 直接点击右侧大纲部分中的链接
+- 首次加载含有 `#` 的 URL
+
+就是这么多了，祝撰写愉快！