Markdown 语法展示

这是一篇用于 Docship 预览的综合 Markdown 文档。它同时覆盖 CommonMark、GitHub Flavored Markdown（GFM）以及常见文档站扩展，方便在 showcase 中比较不同框架的渲染结果。

目录

• 标题与段落
• 文字格式
• 列表
• 链接与图片
• 引用
• 代码
• 表格
• 扩展语法
• 原始 HTML

标题与段落

上面是一级标题。下面演示 Setext 风格标题。

Setext 二级标题

Setext 一级标题

这是一个普通段落。Markdown 中连续的文本会合并为同一段，空一行即可开始新段落。 行末两个空格会产生换行。
这行会出现在上一行的下面。

文字格式

• 斜体、斜体
• 粗体、粗体
• 粗斜体、粗斜体
• 删除线（GFM）
• 行内代码 和 包含 ` 反引号的代码
• 普通链接中的 链接文字
• 转义符号：*星号*、#井号、[方括号]
• 特殊字符：<、>、& 会被正确显示

列表

无序列表

• 第一项
• 第二项
  • 嵌套项 2.1
  • 嵌套项 2.2
    • 第三级项目
• 第三项

有序列表

1. 第一步
2. 第二步
   1. 第二步的子项
   2. 另一个子项
3. 第三步

任务列表

• 已完成任务
• 待完成任务
• 另一个待办事项

定义列表

Markdown

一种轻量级标记语言

GFM

GitHub Flavored Markdown

链接与图片

链接

行内链接

带标题的链接

https://github.com/NekoTick/docship

hello@example.com

也可以使用引用式链接：项目主页。

图片

图片也可以作为链接：

引用

这是一个引用段落。

引用可以包含 粗体、代码 以及链接。

这是嵌套引用。

嵌套引用可以继续包含列表：

• 项目 A
• 项目 B

代码

行内代码

使用 npm run build 构建项目。

围栏代码块

function greet(name) {
  return `Hello, ${name}!`;
}

console.log(greet('Markdown'));

def fibonacci(n):
    if n < 2:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

{
  "name": "docship",
  "markdown": true
}

- const theme = 'light';
+ const theme = 'dark';

缩进代码块

// 四个空格也可以创建代码块
const answer = 42;

表格

对齐与格式

项目比较表

HTML 表格

扩展语法

分隔线

三种写法都表示水平分隔线：

脚注

这里有一个脚注¹，还有一个多行脚注²。

数学公式（LaTeX）

行内公式通常写作 $E = mc^2$。

部分框架需要 KaTeX 或 MathJax 插件才能显示块级公式：

\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6}

Mermaid 图表

部分框架支持直接渲染 Mermaid：

flowchart TD
    A[开始] --> B{构建成功?}
    B -->|是| C[发布页面]
    B -->|否| D[查看日志]

可折叠内容

提示块（部分框架支持）

[!NOTE] 这是一个提示块。

[!TIP] 这是一个技巧提示。

[!WARNING] 这是一个警告提示。

[!IMPORTANT] 这是一个重要提示。

[!CAUTION] 这是一个注意事项。

YAML Front Matter

Front Matter 通常位于文件开头。这里用代码块展示，避免影响当前页面配置：

---
title: Markdown 示例
description: 展示常用 Markdown 语法
---

原始 HTML

Markdown 允许在需要时混入安全的 HTML 标签：

Ctrl + C 复制

H₂O 和 x²

高亮文本

兼容性说明

Docship 会把根目录的 Markdown 文件交给各个框架工作流构建。当前页面就是仓库首页，因此会自动出现在 showcase 的每个框架卡片中；不同框架对数学、Mermaid、提示块和 HTML 扩展的支持可能略有差异。

文档由 Docship Markdown showcase 提供。

1. 脚注可以放在文档末尾。 ↩

2. 脚注内容可以分成多行。 缩进的行仍属于同一个脚注。 ↩

Docship Theme Development Checklist

⚠️ Critical Rules

No Advertisements Policy

• NEVER use any theme or plugin that contains ads
• Some official themes (e.g., @vuepress/theme-vue) contain sponsor/advertisement content - DO NOT USE
• Always check if theme contains ads, sponsor links, or donation prompts before using
• When in doubt, use the framework’s default theme

Known themes/plugins with ads (DO NOT USE):

Recommended ad-free alternatives:

User Content Respect

• Never restrict user filenames (e.g., index.md, temp.md are all valid)
• User markdown content must never break builds regardless of validity
• Invalid image paths, links, etc. should be ignored, not cause errors

Markdown Compatibility

• Use markdown.format: 'md' instead of MDX to avoid JSX parsing errors (Docusaurus)
  • Users may have ${}, <>, {} in their markdown content
  • MDX will treat these as JSX expressions and fail
• VitePress is more lenient with ${} but double curly braces will be treated as Vue template
• Don’t restrict filenames - users can use any name like temp.md
• Handle files with special characters in content gracefully

Docusaurus Configuration

• Don’t use navbar.logo without logo.src - it will throw validation error
• Remove sidebarPath to let Docusaurus auto-generate sidebar from file structure
• Use onBrokenLinks: 'ignore' to prevent build failures on broken links
• Use markdown.hooks.onBrokenMarkdownLinks: 'ignore' (new location in v3.9+)
• Don’t include deprecated options like root-level onBrokenMarkdownLinks
• For local search, use @easyops-cn/docusaurus-search-local (no API key needed)
• Algolia search requires API key - not suitable for generic themes

VitePress Configuration

• Use ignoreDeadLinks: true to prevent build failures on broken/dead links
• VitePress does NOT auto-generate sidebar - need custom script or manual config
• sidebar: 'auto' does NOT work like Docusaurus - only shows current page headings
• Output directory is .vitepress/dist (not build)
• Use srcDir: 'docs' to specify source directory
• Exclude node_modules in content backup
• For local search, use search: { provider: 'local' } (built-in)
• logo.link does NOT support external URLs - need custom theme to override

Sidebar Generation (VitePress)

• Write custom Node.js script to scan directory and generate sidebar config
• Sort entries: files first, then directories (or vice versa for consistency)
• Skip files starting with . or _
• Skip index.md from sidebar items (it’s the folder landing page)
• Capitalize first letter and replace - with spaces for display text

Homepage Selection Logic

Priority order:

1. docs/index.md or content/index.md - explicit homepage
2. docs/README.md or content/README.md - common convention
3. First .md file (sorted alphabetically) - fallback

• Always use sort before head -1 for consistent results
• For Docusaurus: check if slug: / already exists before adding frontmatter
• For VitePress: index.md is automatically the homepage, no frontmatter needed

GitHub Actions / Reusable Workflows

• Reusable workflows MUST be in .github/workflows/ directory
• Use on: workflow_call for workflows that should only be called by others
• Caller workflow must declare permissions for the called workflow to use
• Remove push and workflow_dispatch triggers if workflow should not run directly

Content Backup

• Exclude README.md from root (usually not documentation)
• Exclude hidden directories (.git, .github, etc.)
• Exclude node_modules directory
• Copy all user folders to preserve structure
• Handle empty content directory - create default welcome page

Build & Deploy

• GitHub Pages keeps old version online during build (atomic deployment)
• First deployment shows blank page until complete - this is normal
• Public repos have unlimited GitHub Actions minutes
• Add npm cache to speed up builds: actions/cache@v4 with ~/.npm path

Shell Script Best Practices (GitHub Actions)

• Don’t use sed -i '1s/^/...\n.../' - \n may not work on all systems
• Don’t use heredoc (<< EOF) inside YAML run: blocks - causes syntax errors
• Use printf '%s\n' 'line1' 'line2' for multi-line content
• Use temp files + cat + mv to prepend content to files
• Always quote variables: "$TARGET" not $TARGET

Logo & Branding

• Use https://github.com/USERNAME.png to get user/org avatar
• VitePress: need custom theme (enhanceApp) to make logo link to external URL
• Docusaurus: logo.href + logo.target: '_blank' works for external links
• Set favicon with head: [['link', { rel: 'icon', href: '...' }]] (VitePress)
• Docusaurus favicon can be external URL directly

Testing Scenarios

Before releasing a theme, test with:

• Empty repository (no markdown files)
• Single markdown file
• Nested folder structure
• Files with ${} syntax in content
• Files with JSX-like syntax <Component />
• Files with curly braces {}
• Files with Vue template syntax (VitePress specific)
• Unicode/special characters in filenames
• Very long filenames
• Files starting with _ (usually ignored by default)
• Files containing localhost URLs (dead link check)
• Repository without index.md (homepage fallback logic)

Starlight (Astro) Configuration

• Use npm create astro@latest -- --template starlight for correct project structure
• Starlight v0.33.0+ changed social config from object to array format
  • Old: social: { github: 'url' }
  • New: social: [{ icon: 'github', label: 'GitHub', href: 'url' }]
• Every .md file MUST have title in frontmatter - Starlight will fail without it
• Sidebar slug must be lowercase - uppercase will cause “slug does not exist” error
• autogenerate: { directory: '.' } doesn’t work well - use specific directory names
• Content goes in src/content/docs/ directory
• Output directory is dist
• Use .mdx extension for index file if needed

Rspress Configuration

• Public assets go in docs/public/ (not project root public/)
• Sidebar items must be an array, not 'auto' string
• Output directory is doc_build
• Exclude public directory from sidebar generation
• Config file is rspress.config.ts (TypeScript)

Common Errors & Solutions

Fumadocs Configuration

• Fumadocs is based on Next.js - requires output: 'export' for static build
• Use basePath for GitHub Pages deployment (e.g., /${REPO_NAME})
• Set images: { unoptimized: true } for static export
• Content goes in content/docs/ directory
• Output directory is out (Next.js static export default)
• Every .mdx file should have frontmatter with title and description
• Use create-fumadocs-app with --template +next+fuma-docs-mdx+static for static export
• Fumadocs MDX is the official content source
• Config file is next.config.mjs (ESM)
• Requires fumadocs-mdx/next plugin wrapper
• Set remarkImageOptions: false in source.config.ts to prevent build failures from invalid image paths
• Delete app/llms-full.txt and app/og directories (they depend on exports not in simplified source.ts)
• Clear template’s default content/docs/* before copying user content (removes Hello World page)

Nextra Configuration

• Nextra v4 uses App Router - structure is src/app/ and src/content/
• Requires output: 'export' and images: { unoptimized: true } for static build
• Use basePath via environment variable for GitHub Pages
• Content goes in src/content/ directory
• Output directory is out
• Need mdx-components.js at project root for MDX components
• Use nextra-theme-docs for documentation theme
• Config uses nextra() wrapper with contentDirBasePath option
• Homepage redirect to /docs since content is under /docs route
• Nextra uses MDX - user content with ${}, <>, {} may cause JSX parsing errors
• Set staticImage: false to prevent build failures from invalid image paths

VuePress Configuration

• VuePress 1.x is Vue 2 based - use vuepress@^1.9.10
• ⚠️ DO NOT USE @vuepress/theme-vue - it contains sponsor/advertisement content
• Use default theme @vuepress/theme-default (built-in, no ads)
• Content goes in docs/ directory
• Output directory is docs/.vuepress/dist
• Config file is docs/.vuepress/config.js
• Use base: '/${REPO_NAME}/' for GitHub Pages subdirectory
• themeConfig.logo supports external URLs directly
• themeConfig.sidebar: 'auto' only shows current page headings - need Node.js script for full sidebar
• Homepage is docs/README.md (not index.md) - must rename index.md to README.md
• Use themeConfig.repo for GitHub link in navbar
• Custom styles go in docs/.vuepress/styles/index.styl (Stylus)
• Use enhanceApp.js for client-side customizations (e.g., footer injection)
• Favicon via head: [['link', { rel: 'icon', href: 'URL' }]] - supports external URLs
• VuePress uses Vue template syntax - double curly braces in markdown will be parsed as Vue expressions
• Use @vuepress/plugin-back-to-top for back-to-top button (built-in plugin)
• VuePress 1.x does NOT have native dark mode toggle - custom implementation is complex
• Green scrollbar: apply only to .sidebar selector, not whole page

DocFX Configuration

• DocFX is a .NET-based documentation framework - uses dotnet tool install -g docfx
• Content goes in docs/ directory
• Output directory is _site
• Config file is docfx.json
• Uses toc.yml for navigation structure (root for navbar, docs/ for sidebar)
• _appLogoPath and _appFaviconPath do NOT support external URLs - need custom template
• Use custom template with JavaScript to inject external avatar as logo/favicon
• Remove root toc.yml to hide navbar tabs (e.g., “Docs” tab) when only one section
• Use redirect_url frontmatter in index.md to redirect homepage to docs
• Set _disableContribution: true to hide “Edit this page” link
• Set _appFooter to customize or remove footer
• Sidebar toc.yml format: - name: Title + href: file.md
• Delete invalid toc.yml files from user content subdirectories
• Exclude framework source folders in backup (fumadocs/, nextra/, docute/, etc.)

Docute Configuration

• Docute is a pure frontend framework - no build process needed
• Only needs index.html + markdown files
• Uses CDN for docute.js and docute.css (unpkg.com/docute@4)
• URL routing: / => /README.md, /foo => /foo.md, /foo/ => /foo/README.md
• Sidebar must be manually configured or auto-generated via script
• Logo is a Vue template string - use <span> wrapper with flex layout for avatar + text
• Use darkThemeToggler: true for dark mode toggle
• No npm cache needed since no build process

mdBook Configuration

• mdBook is a Rust-based documentation tool - install via pre-built binary or cargo install mdbook
• Content goes in src/ directory
• Output directory is book/
• Config file is book.toml (TOML format)
• Requires src/SUMMARY.md to define table of contents structure
• Homepage is src/README.md (linked as [Introduction](README.md) in SUMMARY.md)
• SUMMARY.md format: - [Title](path/to/file.md) for chapters
• Use # headers in SUMMARY.md to create section separators
• [output.html] section in book.toml for HTML output settings
• site-url in book.toml for base path (GitHub Pages subdirectory)
• Custom theme via theme/ directory - can override index.hbs, head.hbs, CSS files
• Favicon and logo require custom theme modifications (no direct config option)
• Built-in themes: light, rust, coal, navy, ayu
• default-theme and preferred-dark-theme in [output.html] section
• Supports MathJax via mathjax-support = true
• Built-in search functionality (no additional config needed)

Eleventy Configuration

• Eleventy (11ty) is a JavaScript-based static site generator
• Install via npm install @11ty/eleventy
• Config file is eleventy.config.js or .eleventy.js
• Default input directory is . (project root)
• Default output directory is _site
• Supports multiple template languages: Liquid, Nunjucks, Markdown, HTML, JavaScript
• Use dir.input and dir.output in config to customize directories
• Use pathPrefix for GitHub Pages subdirectory deployment
• Layouts go in _includes/ directory by default
• Data files go in _data/ directory (JSON, JS, or YAML)
• Use frontmatter layout to specify template layout
• Collections are auto-generated from tags or can be custom defined
• Use eleventyConfig.addPassthroughCopy() for static assets
• Markdown files need frontmatter with layout to use templates
• No built-in theme - requires custom CSS/layout

Sphinx Configuration

• Sphinx is a Python-based documentation generator
• Install via pip install sphinx furo myst-parser
• Config file is conf.py (Python)
• Default source directory is docs/ or project root
• Default output directory is _build/html/
• Use myst-parser extension to support Markdown (default is reStructuredText)
• Furo is a modern, clean theme (BSD license)
• Use toctree directive to define navigation structure
• html_theme = 'furo' to use Furo theme
• html_logo and html_favicon for branding
• html_theme_options for theme customization
• Custom CSS goes in _static/ directory
• Build with sphinx-build -b html docs docs/_build/html
• License is BSD (Sphinx) + MIT (Furo) - very permissive

Docus Configuration

• Docus is a Nuxt 4-based documentation framework (MIT license)
• Install via npm install docus nuxt better-sqlite3
• Config file is nuxt.config.ts with extends: ['docus']
• Content goes in content/ directory with number prefixes for ordering (e.g., 1.docs/, 2.guide/)
• Output directory is .output/public/
• Use nuxt generate for static build
• Homepage is special - content/index.md renders as landing page without sidebar
• Documentation pages need subdirectory - put docs in content/1.docs/ to get sidebar layout
• Number prefixes in filenames control order: 1.index.md, 2.guide.md → /index, /guide
• Use .navigation.yml in directories to set section titles
• Frontmatter title is required for each page
• app.config.ts goes in app/ directory for theme configuration
• header.title and header.logo for branding
• socials.github for GitHub link in header
• Custom components override defaults - put in app/components/app/
• AppHeaderLogo.vue - customize logo + title display
• AppFooterLeft.vue - customize footer left (attribution)
• AppFooterRight.vue - customize footer right (social icons, theme toggle)
• Set empty AppFooterRight.vue to remove duplicate theme toggle
• Logo click should link to /docs not / (override AppHeaderLogo.vue with <NuxtLink to="/docs">)
• Favicon via app.head.link in nuxt.config.ts
• Prerendering issue: Nuxt only prerenders routes it can crawl from homepage
• Must explicitly list routes in nitro.prerender.routes or generate dynamically
• Convert filenames to lowercase for routes (uppercase causes 404)
• Create index.html redirect after build for root → /docs
• robots: { robotsTxt: false } to avoid base URL error
• @nuxtjs/mcp-toolkit warning is normal - not compatible with static generate

General Lessons Learned

Framework Categories

1. Build-required frameworks (need npm install + build):

   • Docusaurus, VitePress, Starlight, Rspress, Fumadocs, Nextra
   • Need npm cache for faster builds
   • Output to specific directories (build/, dist/, out/, doc_build/)

2. Pure frontend frameworks (no build, CDN-based):

   • Docsify, Docute
   • Just HTML + markdown files
   • Faster deployment, simpler setup

3. Next.js-based frameworks:

   • Fumadocs, Nextra
   • Require output: 'export' for static build
   • Require images: { unoptimized: true } for static export
   • Use basePath for GitHub Pages subdirectory

Common Pitfalls

• Image handling: MDX/Next.js frameworks try to import images - disable with remarkImageOptions: false or staticImage: false
• Template default content: Many templates include “Hello World” or demo content - clear before copying user content
• CLI argument changes: Framework CLIs change frequently - check latest docs (e.g., create-fumadocs-app changed from --name --template --src to --template +next+fuma-docs-mdx+static)
• API version changes: Check for breaking changes (e.g., Starlight social config changed from object to array)
• Sidebar in sidebar: Some frameworks show index page in sidebar - use index: true frontmatter to hide it

Branding Consistency

For all frameworks, implement:

• Logo: User avatar + username/reponame in top-left
• Favicon: User’s GitHub avatar (https://github.com/USERNAME.png)
• GitHub link: Icon or text link to repository (right side of navbar)
• Title: username/reponame in browser tab
• Footer: Powered by NekoTick · {Framework} with links to both projects

Footer Format

All workflows must include a footer with attribution: Powered by NekoTick · {Framework}

• NekoTick link: https://github.com/NekoTick/NekoTick
• Framework link: GitHub repository of the framework (not official website)
• NekoTick comes first (deployment service provider)
• Framework comes second (underlying tool)
• Use · as separator
• Links should open in new tab (target="_blank")

Logo Implementation Patterns

Sidebar Generation

• Auto-generate from directory structure when possible
• Convert filenames to titles: my-file.md → My File
• Handle nested directories as collapsible groups
• Skip README.md / index.md from sidebar items (they’re folder landing pages)
• Use sort for consistent ordering

Testing Checklist (Updated)

• Files with invalid image paths (should not break build)
• Files with special markdown syntax (${}, <>, {})
• Empty repository (should show welcome page)
• Nested folder structure (should generate proper sidebar)
• Repository without index.md (should use first doc as homepage)

Multi-Language Support

• VitePress/Docusaurus i18n is static - requires manual translation files
• No automatic translation built-in
• Options: browser translation, or integrate translation API (costs money)
• Structure: docs/en/, docs/zh/ etc. for each language

Adding New Framework

When adding a new documentation framework to Docship:

1. Create Workflow File

• Create .github/workflows/{framework}.yml
• Use on: workflow_call with base_path_suffix and deploy inputs
• Follow existing workflow structure for consistency

2. Add Footer Attribution

Every framework MUST include a footer with: Powered by NekoTick · {Framework}

• NekoTick link: https://github.com/NekoTick/NekoTick
• Framework link: GitHub repository of the framework
• Use · (middle dot) as separator
• Links should open in new tab (target="_blank")

Footer implementation by framework type:

3. Update Showcase

• Add build job in showcase.yml with name: {framework}
• Add to needs array in combine job
• Add build result env variable (e.g., BUILD_FRAMEWORK)
• Add to RESULTS array in combine step
• Add entry in showcase/frameworks.json with GitHub link(s)

frameworks.json format:

{
  "framework-name": {
    "links": ["https://github.com/org/repo"]
  },
  "framework-with-theme": {
    "links": ["https://github.com/org/framework", "https://github.com/org/theme"]
  }
}

4. Update Documentation

• Add framework to README.md supported frameworks table
• Add framework-specific notes to CHECKLIST.md if needed

⚠️ This is a test file for DocShip development. The content below is sample documentation.

Code Block Test

Basic Code Blocks

// JavaScript code
const greeting = "Hello, World!";
console.log(greeting);

# Python code
def hello():
    print("Hello")

# Shell script
echo "Hello World"

Empty Code Blocks

Inline Code

Normal inline code: const x = 1

Double backticks: code with `backtick` inside

Long Line

aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa

Normal Content

This should render fine.

⚠️ This is a test file for DocShip development. The content below is sample documentation.

HTML Edge Cases Test

Script Tags (should be removed)

Script tags should be sanitized by the build process.

Style Tags (should be removed)

Style tags should also be sanitized.

Event Handlers

Event handlers in HTML should be handled:

• onclick attributes
• onerror attributes
• onload attributes

HTML Comments

Valid HTML

Tables in HTML

Details/Summary

Normal Content

This paragraph should render normally.

Regular markdown works fine:

• List item 1
• List item 2
• List item 3

Bold text and italic text work as expected.

⚠️ This is a test file for DocShip development. The content below is sample documentation.

Malformed Lists Test

Mixed List Markers

• Dash item

• Asterisk item

• Plus item

• Back to dash

Inconsistent Indentation

• Level 1
• One space
• Two spaces
• Three spaces - Four spaces
  • Five spaces

Numbered List Issues

1. First
2. Third (skipped 2)
3. Two (out of order)
4. Ten
5. Eleven
6. Back to one

No Space After Marker

-No space *Also no space 1.Number no space

Task List Variations

• Unchecked
• Checked
• Capital X
• Space inside
• [] No space
• [?] Question mark -[ ] No space before bracket

Deeply Nested

• L1
  • L2
    • L3
      • L4
        • L5
          • L6
            • L7
              • L8
                • L9
                  • L10

Empty List Items

• Content

Normal Content

This should render normally.

⚠️ This is a test file for DocShip development. The content below is sample documentation.

Math Syntax Test

Inline Math

Inline: $E = mc^2$ Another: $\sum_{i=1}^{n} i$ Complex: $\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$

Block Math

$$ E = mc^2 $$

$$ \sum_{i=1}^{n} i = \frac{n(n+1)}{2} $$

$$ \begin{aligned} a &= b + c \ d &= e + f \end{aligned} $$

Unclosed Math

$unclosed inline

$$ unclosed block

$$ also unclosed

Dollar Signs (Not Math)

Price: $100 Range: $50 - $100 Currency: $USD

Mixed Valid and Invalid

Valid: $x^2$ Invalid: $ Also invalid: $$ Back to valid: $y = mx + b$

LaTeX Commands

$\alpha \beta \gamma$ $\frac{1}{2}$ $\sqrt{x}$ $\vec{v}$ $\hat{i}$

Normal Content

This should render normally.

⚠️ This is a test file for DocShip development. The content below is sample documentation.

Malformed Tables Test

Missing Separator Row

| Header 1 | Header 2 | | Cell 1 | Cell 2 |

Inconsistent Columns

| A | B | C | |—|—| | 1 | 2 | 3 | 4 | 5 | | x |

No Pipes at Edges

Only Separator

|—|—|—|

Empty Table

Pipes in Content

Very Wide Table

Nested Markdown in Table

Normal Content

This should render fine.