authoring-documentation
Guidelines for writing documentation files including 11ty templates, Eleventy shortcodes, JSDoc annotations, and markdown content. Use this skill whenever the user works with documentation markdown files, Vale prose linting errors, Eleventy shortcodes (dodont, example), frontmatter, JSDoc annotations that must pass Vale, or the documentation site. Also trigger when the user mentions Vale errors, adding terms to the vocabulary, suppressing Vale rules, or writing and fixing prose in .md or .ts files.
소스 정보
- 저장소
- NVIDIA/elements
- 최근 소스 활동
- 2026년 8월 13일 13:59
- 감지된 SKILL.md 언어
- 영어
- 스타
- 93
- 포크
- 18
설치 방법
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
소스 파일 검토
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
SKILL.md 표시 중
SKILL.md
소스 지침 · 읽기 전용 미리보기- name
- authoring-documentation
- description
- Guidelines for writing documentation files including 11ty templates, Eleventy shortcodes, JSDoc annotations, and markdown content. Use this skill whenever the user works with documentation markdown files, Vale prose linting errors, Eleventy shortcodes (dodont, example), frontmatter, JSDoc annotations that must pass Vale, or the documentation site. Also trigger when the user mentions Vale errors, adding terms to the vocabulary, suppressing Vale rules, or writing and fixing prose in .md or .ts files.
# Documentation (`*.md`)
You MUST review @projects/site/src/docs/internal/guidelines/documentation.md before making any documentation changes.
## When to Use This Skill
- Creating or updating markdown documentation files
- Working with 11ty templates in the documentation site
- Using or creating Eleventy shortcodes
- Writing API documentation or component guides
- Updating internal guidelines or developer documentation
- Fixing Vale prose-linting errors in markdown or JSDoc
## Key Principles
1. **Frontmatter Required**: All documentation files must include proper frontmatter with title and layout
2. **Eleventy Shortcodes**: Use built-in shortcodes for common patterns (code examples, callouts, etc.)
3. **Clear Structure**: Use proper heading hierarchy and table of contents for long documents
4. **Code Examples**: Include working code examples with proper syntax highlighting
5. **Cross-References**: Link to related documentation and guidelines using proper paths
## Prose Linting (Vale)
### How Vale Runs
- **Pre-commit** (via lint-staged): automatically lints staged non-test `*.ts` and `*.md` files
- **CI**:runs as part of `pnpm run ci`
- **Manual**:`pnpm run lint:vale` from the repo root (pass specific files as args to narrow scope)
### Rule Sets by File Type
- `*.md`:Vale, Google, write-good, Elements (full rule set)
- `*.ts`:Vale, write-good, Elements (no Google rules or spelling checks to reduce noise on code identifiers)
- `*.examples.ts`:same as `*.ts` plus three summary rules: `SummaryStyle`, `SummaryActionable`, `SummaryGerund`
### Common Errors and Fixes
| Rule | Trigger | Fix |
| ----------------------- | --------------------------------------------- | ---------------------------------------------------------------------------- |
| `Google.Latin` | `e.g.`, `i.e.` | Use "for example," "that is" |
| `Google.Passive` | Passive voice | Rewrite in active voice |
| `Google.Quotes` | Punctuation outside quotes | Move commas/periods inside quotation marks |
| `Elements.Branding` | `nvidia`, `Nvidia` | Always use `NVIDIA` |
| `Elements.Terminology` | `web component` | Use `Web Component` / `Web Components` |
| `Vale.Spelling` | Unknown term | Add the term to `config/vale/styles/config/vocabularies/Elements/accept.txt` |
| `Elements.SummaryStyle` | Weak openers like "This example demonstrates" | Lead with what the example does or when to use it |
### Suppressing Rules
Use sparingly, and re-enable immediately after the affected content:
```markdown
<!-- vale Google.Quotes = NO -->
content here
<!-- vale Google.Quotes = YES -->
```
### Key Files
- `.vale.ini`:root config (rule toggles, file-type scopes, token ignores)
- `config/vale/styles/Elements/`:custom rules (Branding, Terminology, Summary\*)
- `config/vale/styles/config/vocabularies/Elements/accept.txt`:approved vocabulary
## References
- [Documentation Guidelines](/projects/site/src/docs/internal/guidelines/documentation.md)
- [Examples Guidelines](/projects/site/src/docs/internal/guidelines/examples.md)
- [Vale Config](/.vale.ini)
- [Custom Vale Rules](/config/vale/styles/Elements/)
GitHub에서 보기