nx-docs-writer

jaysoo 的头像作者 jaysoo

用于nx.dev文档的文档编写和编辑。在添加、编辑或润色文档、迁移Markdoc到Starlight、调试内容转换或修复文档站点问题时使用。触发于“docs”、“documentation”、“nx.dev”、“Markdoc”、“Starlight”、“astro-docs”

📖 中文导读:用于nx.dev文档的文档编写和编辑。在添加、编辑或润色文档、迁移Markdoc到Starlight、调试内容转换或修复文档站点问题时使用。触发于“docs”、“documentation”、“nx.dev”、“Markdoc”、“Starlight”、“astro-docs” 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: nx-docs-writer description: Documentation writing and editing for nx.dev docs. Use when adding, editing, or polishing documentation, migrating Markdoc to Starlight, debugging content transformations, or fixing documentation site issues. Triggers on "docs", "documentation", "nx.dev", "Markdoc", "Starlight", "astro-docs".

Nx Documentation Writer

Repository Structure

nx-dev/ (Next.js Site)

Main documentation site - Next.js with sub-packages:

  • nx-dev/feature-search/ - Algolia search
  • nx-dev/ui-blog/ - Blog components
  • nx-dev/ui-common/ - Shared UI
  • nx-dev/data-access-documents/ - Document processing

astro-docs/ (Starlight)

Standalone docs using Astro/Starlight framework.

URL Generation

Rule: Lowercase + replace special chars with dashes + remove extension

File Path URL
features/CI Features/split-e2e-tasks.mdoc /docs/features/ci-features/split-e2e-tasks
concepts/mental-model.mdoc /docs/concepts/mental-model

Markdoc Syntax

Component Names

Use underscores: side_by_side NOT side-by-side

JSON in Tags

{% graph %}
```json
{"nodes": [...]}

{% /graph %}

- Use code fences for JSON (never inline with escaped quotes)
- JSON available in `data-code` attribute
- Never escape template blocks: `{% %}` not `\{% %\}`

## Markdoc to Starlight Migration

| Markdoc | Starlight |
|---------|-----------|
| `{% tabs %}...{% /tabs %}` | `#### Tab Label` headers |
| `{% callout type="note" %}` | `:::note` |
| `{% callout type="warning" %}` | `:::caution` |
| `{% callout type="check" %}` | `:::tip` |
| `{% callout type="error" %}` | `:::danger` |
| `{% graph %}` | Remove (not supported) |

**Before transforming**: Validate balanced tags first!

```javascript
const content = fs.readFileSync('file.md', 'utf-8');
const open = (content.match(/\{% tabs %\}/g) || []).length;
const close = (content.match(/\{% \/tabs %\}/g) || []).length;
if (open !== close) console.error(`Unbalanced: ${open} open, ${close} close`);

Frontmatter Rules

  • Frontmatter title = h1 - NEVER duplicate with content h1
  • Sidebar labels can differ from page title
  • Code blocks are not headings - # in shell scripts isn't markdown h1

Testing Documentation

Build & Serve

nx run PROJECT:build
npx serve dist -p 8000  # Use -p not --port

Verification

# Check rendered HTML
curl -s http://localhost:8000/path | grep "pattern"

# Clear cache between tests
rm -rf .astro dist

# Find duplicate h1s
grep -r "^#\s" --include="*.md" docs/

Search only works in production builds, not dev server.

Common Mistakes

  • Don't duplicate theme switcher in mobile menu (Starlight handles it)
  • Don't assume all UI elements are in Header.astro
  • Don't use lg:hidden when you mean xl:hidden
  • Don't override entire Starlight components for simple style fixes
  • Don't assume markdown files are well-formed - validate first
  • Don't create complex regex for malformed input - fix the source
  • Don't use inline JSON in Markdoc tags with escaped quotes

Best Practices

  • Check what Starlight provides by default FIRST
  • Prefer CSS fixes in global.css over component overrides
  • Clear Astro cache (.astro) when transformations aren't reflecting
  • Test individual files with Node scripts before full integration
  • After file changes, wait 5-10 seconds for rebuild before verification
  • Use [data-theme='dark'] selector for dark mode styles
  • Use Tailwind theme colors theme('colors.slate.600') for consistency

When making documentation changes, check:

  • redirect-rules-docs-to-astro.js - Redirect mappings
  • next.config.js - Rewrites and redirects
  • map.json - Routing configuration