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