SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillszhihu-html

zhihu-html

Frontend & websites

View repository

Updated 10-15 18:51

About this skill

Zhihu HTML Converter

Convert Markdown to HTML compatible with the Zhihu editor.

⚠️ Path resolution (important)

The scripts for this skill are located in the directory where SKILL.md is. Before executing any script,you mustfirst determine the actual path of this file, and derive the script directory from it.

Rules: In all the following documents, $SKILL_DIR placeholders should be replaced with the directory path where this SKILL.md file is located.

For example: if this file is located at /Users/xxx/Desktop/AI/skills/zhihu-html/SKILL.md, then $SKILL_DIR = /Users/xxx/Desktop/AI/skills/zhihu-html。

SKILL_DIR="<本 SKILL.md 文件所在目录的绝对路径>"

Quick Start

Convert from a Markdown file

node "$SKILL_DIR/scripts/convert.mjs" --input article.md --output article.html

Read from stdin

echo "# 标题\n\n段落内容" | node "$SKILL_DIR/scripts/convert.mjs" --output article.html

Output to stdout

node "$SKILL_DIR/scripts/convert.mjs" --input article.md

Link handling configuration

Supports distinguishing the handling of internal links and external links:

  • Internal links: convert to a regular <a> tag
  • External links: convert to the Zhihu <sup> citation format (requires AI-generated data-text)

Configuration method

Modify the scripts/extract-refs.mjs object in the LINK_CONFIG file:

const LINK_CONFIG = {
  enabled: true,
  internalDomains: [
    'zhihu.com'  // 会匹配 zhihu.com 及其所有子域名
  ],
  internalPatterns: [
    // 可选：添加正则表达式模式进行更精确的匹配
    // '^https://www\\.zhihu\\.com/question/\\d+',
    // '^https://zhuanlan\\.zhihu\\.com/p/\\d+'
  ]
};

Configuration description

  • enabled: whether to enable the link distinction feature (default true）
  • internalDomains: list of internal domains, supports subdomain matching
    • For example "zhihu.com" will match zhihu.com、www.zhihu.com、zhuanlan.zhihu.com , etc.
  • internalPatterns: list of regular expression patterns for internal links
    • Used for more precise URL matching

Default behavior

The default configuration treats all links under the zhihu.com domain as internal links, and other links as external links.

Workflow

This skill works as a three-step pipeline; AI only needs to process the streamlined citation JSON, without reading the full HTML:

Step 1: Convert Markdown → Zhihu HTML (with placeholder markers)

node "$SKILL_DIR/scripts/convert.mjs" -i article.md -o article.html

The script handles all deterministic format conversion. All links are output as <!-- REF:N ... --> placeholder markers.

Step 2: Extract the citation list (streamlined JSON for AI to read)

node "$SKILL_DIR/scripts/extract-refs.mjs" -i article.md -o refs.json

Extract all links, and mark their types (internal/external) according to the built-in configuration. Example output:

[
  {
    "numero": 1,
    "url": "https://www.zhihu.com/question/12345",
    "originalText": "知乎问题",
    "context": "这里有一个知乎问题的链接。",
    "type": "internal",
    "dataText": ""
  },
  {
    "numero": 2,
    "url": "https://www.langchain.com/report",
    "originalText": "报告",
    "context": "LangChain 的调查报告显示，超过 50% 的开发者已经在使用 Agent。",
    "type": "external",
    "dataText": ""
  }
]

Based on the url、originalText、context information (you may also visit the URL to get the page title), for type: "external" citations, fill in the dataText field. Internal links (type: "internal") do not need dataText。

Rules for AI-generated data-text:

  • Prefer Chinese descriptions, such as "Alibaba Cloud: The engineering of AI Agents is underestimated"
  • Keep the original English titles for academic papers, such as "Why Do Multi-Agent LLM Systems Fail?"
  • Official documentation may use the "XXX Official Documentation" format
  • Concise and clear, so that readers can tell what is cited just by seeing the title

Step 3: Apply citations → generate the final HTML

node "$SKILL_DIR/scripts/apply-refs.mjs" -i article.html -r refs.json -o final.html

The script replaces the <!-- REF:N ... --> placeholder markers in the HTML with:

  • type: "internal" → <a href="...">文字</a>
  • type: "external" → 文字<sup ...>[N]</sup>

When -o is not specified, the input file is overwritten by default.

Zhihu HTML specifications

Allowed tags

  • <h1> — article title (only one)
  • <h2> — section heading
  • <p> — paragraph
  • <b> — bold
  • <code> — inline code
  • <a> — In-site hyperlink (configuration required)
  • <sup data-text="..." data-url="..." ...> — External reference/hyperlink

Retained tags

  • <ul> <ol> <li> — List
  • <table> <thead> <tbody> <tr> <th> <td> — Table
  • <pre><code> — Code block
  • <img> — Image

Disabled tags

  • Do not use <h3> and lower-level headings (downgraded to <p><b>...</b></p>）
  • Do not use <blockquote> quote tags (downgraded to <p>）
  • Do not use <hr> horizontal rule
  • External links do not use <a> tags (use <sup> citation format)

Hyperlink format

Zhihu handles hyperlinks in two ways:

  1. In-site links(configuration required): retained as regular <a> tags
<a href="https://zhuanlan.zhihu.com/p/123456">文章标题</a>
  1. External links(default): converted to <sup> citation format
<sup data-text="描述标题" data-url="链接地址" data-draft-node="inline" data-draft-type="reference" data-numero="序号">[序号]</sup>
  • data-text Generated by AI based on context and URL content (see Workflow Step 2)
  • Numbering increases from 1 in order of first appearance
  • When the same link appears multiple times, keep the first number

Paragraph rules

  • Wrap each paragraph with <p> wrapped
  • Do not use <br> line breaks; split into multiple <p>
  • <sup> immediately follows the quoted content, with no space

Options

convert.mjs

Option Description Default
-i, --input Input Markdown file stdin
-o, --output Output HTML file stdout
--wrap Wrap in a complete HTML document (including meta charset) off

extract-refs.mjs

Option Description Default
-i, --input Input Markdown file required
-o, --output Output JSON file stdout

apply-refs.mjs

Option Description Default
-i, --input HTML file containing placeholder markers required
-r, --refs Citation JSON file filled in by AI required
-o, --output Output final HTML file Overwrite input

Markdown to Zhihu HTML comparison

Markdown Zhihu HTML
# 标题 <h1>标题</h1>
## 标题 <h2>标题</h2>
**加粗** <b>加粗</b>
`代码` <code>代码</code>
[文字](站内链接) <a href="站内链接">文字</a>(configuration required)
[文字](站外链接) Script outputs 文字<!-- REF:N url="站外链接" text="文字" -->, AI replaces it with 文字<sup ...>[N]</sup>
Paragraph <p>段落</p>
### 三级标题 Converted to <p><b>三级标题</b></p>
List Retain <ul>/<ol>/<li>
Table Retain <table>
Code block Retain <pre><code>
Image Retain <img>
--- Ignore
> 引用 Converted to <p> paragraphs

Example

Input (Markdown)

# AI Agent 的未来

**AI Agent** 正在改变软件开发的方式。

## 背景

LangChain 的调查 [报告](https://www.langchain.com/report) 显示，
超过 50% 的开发者已经在使用 Agent。

另一项研究 [论文](https://arxiv.org/paper) 也证实了这一趋势。

在[知乎上的讨论](https://www.zhihu.com/question/123456)中，
很多开发者分享了他们的实践经验。

## 技术实现

关于具体的实现方式，可以参考 [OpenAI 的官方文档](https://platform.openai.com/docs)。

同时，[这篇知乎专栏文章](https://zhuanlan.zhihu.com/p/654321) 也提供了很好的中文教程。

## 结论

前面提到的 [报告](https://www.langchain.com/report) 还发现了更多有趣的数据。

Output (Zhihu HTML)

Phase 1 script output (including placeholder markers):

<h1>AI Agent 的未来</h1>
<p><b>AI Agent</b> 正在改变软件开发的方式。</p>
<h2>背景</h2>
<p>LangChain 的调查 <!-- REF:1 url="https://www.langchain.com/report" text="报告" --> 显示，超过 50% 的开发者已经在使用 Agent。</p>
<p>另一项研究 <!-- REF:2 url="https://arxiv.org/paper" text="论文" --> 也证实了这一趋势。</p>
<p>在<!-- REF:3 url="https://www.zhihu.com/question/123456" text="知乎上的讨论" -->中，很多开发者分享了他们的实践经验。</p>
<h2>技术实现</h2>
<p>关于具体的实现方式，可以参考 <!-- REF:4 url="https://platform.openai.com/docs" text="OpenAI 的官方文档" -->。</p>
<p>同时，<!-- REF:5 url="https://zhuanlan.zhihu.com/p/654321" text="这篇知乎专栏文章" --> 也提供了很好的中文教程。</p>
<h2>结论</h2>
<p>前面提到的 <!-- REF:1 url="https://www.langchain.com/report" text="报告" --> 还发现了更多有趣的数据。</p>

Citation JSON extracted in Phase 2 (AI needs to fill in the external type dataText):

[
  {
    "numero": 1,
    "url": "https://www.langchain.com/report",
    "originalText": "报告",
    "context": "LangChain 的调查 [报告]...",
    "type": "external",
    "dataText": ""  // AI 填写
  },
  {
    "numero": 3,
    "url": "https://www.zhihu.com/question/123456",
    "originalText": "知乎上的讨论",
    "context": "在[知乎上的讨论]...",
    "type": "internal",
    "dataText": ""  // 站内链接不需要填写
  }
]

Final output after Phase 3 AI processing:

<h1>AI Agent 的未来</h1>
<p><b>AI Agent</b> 正在改变软件开发的方式。</p>
<h2>背景</h2>
<p>LangChain 的调查 报告<sup data-text="LangChain：Agent 工程现状调查报告" data-url="https://www.langchain.com/report" data-draft-node="inline" data-draft-type="reference" data-numero="1">[1]</sup> 显示，超过 50% 的开发者已经在使用 Agent。</p>
<p>另一项研究 论文<sup data-text="Why Do Multi-Agent LLM Systems Fail?" data-url="https://arxiv.org/paper" data-draft-node="inline" data-draft-type="reference" data-numero="2">[2]</sup> 也证实了这一趋势。</p>
<p>在<a href="https://www.zhihu.com/question/123456">知乎上的讨论</a>中，很多开发者分享了他们的实践经验。</p>
<h2>技术实现</h2>
<p>关于具体的实现方式，可以参考 OpenAI 的官方文档<sup data-text="OpenAI Platform Documentation" data-url="https://platform.openai.com/docs" data-draft-node="inline" data-draft-type="reference" data-numero="4">[4]</sup>。</p>
<p>同时，<a href="https://zhuanlan.zhihu.com/p/654321">这篇知乎专栏文章</a> 也提供了很好的中文教程。</p>
<h2>结论</h2>
<p>前面提到的 报告<sup data-text="LangChain：Agent 工程现状调查报告" data-url="https://www.langchain.com/report" data-draft-node="inline" data-draft-type="reference" data-numero="1">[1]</sup> 还发现了更多有趣的数据。</p>

File structure

scripts/

  • convert.mjs — Markdown → Zhihu HTML (including placeholder markers)
  • extract-refs.mjs — Extract citation list + context from Markdown, output JSON
  • apply-refs.mjs — Replace placeholder markers in HTML with the AI-filled JSON to generate the final HTML

assets/

  • example.md — Example Markdown input
  • example.html — Corresponding Zhihu HTML output (including placeholder markers)