Initial commit
This commit is contained in:
Zhongwei Li
15
.claude-plugin/plugin.json
Normal file
15
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,15 @@
|
||||
{
|
||||
"name": "technical-writer",
|
||||
"description": "Technical documentation specialist for README files, API docs, user guides, specifications, and release notes with Obsidian vault management",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Scott",
|
||||
"email": "scott.jungling@gmail.com"
|
||||
},
|
||||
"skills": [
|
||||
"./skills"
|
||||
],
|
||||
"agents": [
|
||||
"./agents"
|
||||
]
|
||||
}
|
||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# technical-writer
|
||||
|
||||
Technical documentation specialist for README files, API docs, user guides, specifications, and release notes with Obsidian vault management
|
||||
9
agents/obsidian-vault-manager.md
Normal file
9
agents/obsidian-vault-manager.md
Normal file
@@ -0,0 +1,9 @@
|
||||
---
|
||||
name: obsidian-vault-manager
|
||||
description: Expert in managing Obsidian vaults using obsidian-cli for reading, writing, searching, and organizing markdown notes
|
||||
tools: Read, Write, Edit, Grep, Glob, Bash, TodoWrite
|
||||
model: inherit
|
||||
color: purple
|
||||
---
|
||||
|
||||
You must use the obsidian-vault-manager skill.
|
||||
9
agents/technical-writer.md
Normal file
9
agents/technical-writer.md
Normal file
@@ -0,0 +1,9 @@
|
||||
---
|
||||
name: technical-writer
|
||||
description: Expert in technical documentation including README files, API docs, user guides, specifications, release notes, and inline documentation. Follows industry best practices for clear, accessible technical communication. Use for all documentation creation, editing, reviewing, or structuring tasks. Examples: <example>user: "Need to create a README for this project" assistant: "Let me use the technical-writer agent to create a comprehensive README" <commentary>README creation requires structured documentation expertise.</commentary></example> <example>user: "API documentation is unclear" assistant: "I'll use the technical-writer agent to improve the documentation" <commentary>Technical documentation improvements need style guide expertise.</commentary></example>
|
||||
tools: Read, Write, Edit, MultiEdit, Glob, Grep
|
||||
model: inherit
|
||||
color: cyan
|
||||
---
|
||||
|
||||
You must use the technical-writer skill.
|
||||
97
plugin.lock.json
Normal file
97
plugin.lock.json
Normal file
@@ -0,0 +1,97 @@
|
||||
{
|
||||
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||
"pluginId": "gh:sjungling/claude-plugins:plugins/technical-writer",
|
||||
"normalized": {
|
||||
"repo": null,
|
||||
"ref": "refs/tags/v20251128.0",
|
||||
"commit": "d1cfaaa4b3a03ea0bde5b10f2b1d8283a2db432f",
|
||||
"treeHash": "320df38453591301de54e52ae3e2a384a71c2e4a0c94c045d7b8b528a38050c0",
|
||||
"generatedAt": "2025-11-28T10:28:23.232311Z",
|
||||
"toolVersion": "publish_plugins.py@0.2.0"
|
||||
},
|
||||
"origin": {
|
||||
"remote": "git@github.com:zhongweili/42plugin-data.git",
|
||||
"branch": "master",
|
||||
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
|
||||
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
|
||||
},
|
||||
"manifest": {
|
||||
"name": "technical-writer",
|
||||
"description": "Technical documentation specialist for README files, API docs, user guides, specifications, and release notes with Obsidian vault management",
|
||||
"version": "1.0.0"
|
||||
},
|
||||
"content": {
|
||||
"files": [
|
||||
{
|
||||
"path": "README.md",
|
||||
"sha256": "9eb53ef122353a39fbc72da6d9f3bea603534b88e4bfbd32d3e4734dd776d9d5"
|
||||
},
|
||||
{
|
||||
"path": "agents/technical-writer.md",
|
||||
"sha256": "dd24c1a12457f41393073a7d94a647e4a2e0eb0635f51e2fbdc60e75fd547518"
|
||||
},
|
||||
{
|
||||
"path": "agents/obsidian-vault-manager.md",
|
||||
"sha256": "c571b37135753e32678a84a25118ffdb41b834b8645dfeda72e1d9f5cb6f3b9f"
|
||||
},
|
||||
{
|
||||
"path": ".claude-plugin/plugin.json",
|
||||
"sha256": "bb42882b629f7005e4bf3ca1d3b187704cc355102f25194bb6303ac41582b58c"
|
||||
},
|
||||
{
|
||||
"path": "skills/obsidian-vault-manager/SKILL.md",
|
||||
"sha256": "347c4f5647068b3ba4ce4ca32f1dec8f47a7ce4395b56986b12f66c28fd262ed"
|
||||
},
|
||||
{
|
||||
"path": "skills/obsidian-vault-manager/references/obsidian-syntax.md",
|
||||
"sha256": "a055323ef6e6086538177a40d86dca52b9694ca1e9a9f99b82900828e1794cd8"
|
||||
},
|
||||
{
|
||||
"path": "skills/obsidian-vault-manager/references/obsidian-cli-reference.md",
|
||||
"sha256": "fe470673f4b966ae5ea64b4a4b9e95a4fe9ab682539dc343e0e88ba61ecf41a1"
|
||||
},
|
||||
{
|
||||
"path": "skills/obsidian-vault-manager/assets/templates/meeting.md",
|
||||
"sha256": "787d9c4ad320122b34cdd47c8a76e243ddf0bade4de1c7f8813ef61fa0b25d35"
|
||||
},
|
||||
{
|
||||
"path": "skills/obsidian-vault-manager/assets/templates/daily-note.md",
|
||||
"sha256": "40cf62442f58bbe17069df083ff0b37ca2320e89943f6120c3e6dfe1517e51d9"
|
||||
},
|
||||
{
|
||||
"path": "skills/obsidian-vault-manager/assets/templates/project.md",
|
||||
"sha256": "d5763065992ff3fb8a0ed986e3a4954cae3c407c2ef10d0bfb895e5c87c11196"
|
||||
},
|
||||
{
|
||||
"path": "skills/obsidian-vault-manager/assets/templates/meeting-note-template.md",
|
||||
"sha256": "5ba932d56c03151abe4592e1011b3108bbfadf46d4a23833d141ba117cfac673"
|
||||
},
|
||||
{
|
||||
"path": "skills/obsidian-vault-manager/assets/templates/project-note-template.md",
|
||||
"sha256": "2465adec1ffd893fbebc1a56f87c62f964485dbdd12f7da2f5e4b40afb9dc21f"
|
||||
},
|
||||
{
|
||||
"path": "skills/obsidian-vault-manager/assets/templates/daily-note-template.md",
|
||||
"sha256": "0ede0223d00ad656acbc3658cdecee32c10af3d40b55655b2fe5e3ff41080fca"
|
||||
},
|
||||
{
|
||||
"path": "skills/technical-writer/SKILL.md",
|
||||
"sha256": "672a711e5a8be546d086afd335e8e57b6b766a1e9726400f59089fa542da02ee"
|
||||
},
|
||||
{
|
||||
"path": "skills/technical-writer/references/style-guide.md",
|
||||
"sha256": "702666ca419bfe286227fbca7e80814e80c08baa0ab9147263a53ae30fdecd55"
|
||||
},
|
||||
{
|
||||
"path": "skills/technical-writer/scripts/validate_markdown.py",
|
||||
"sha256": "55334da800b8527355f26ba4cbfd885df06b9e20c8a17874a830173b7818ae99"
|
||||
}
|
||||
],
|
||||
"dirSha256": "320df38453591301de54e52ae3e2a384a71c2e4a0c94c045d7b8b528a38050c0"
|
||||
},
|
||||
"security": {
|
||||
"scannedAt": null,
|
||||
"scannerVersion": null,
|
||||
"flags": []
|
||||
}
|
||||
}
|
||||
168
skills/obsidian-vault-manager/SKILL.md
Normal file
168
skills/obsidian-vault-manager/SKILL.md
Normal file
@@ -0,0 +1,168 @@
|
||||
---
|
||||
name: obsidian-vault-manager
|
||||
description: Expert in managing Obsidian vaults using obsidian-cli workflows for reading, writing, searching, moving, and organizing notes while preserving wiki-link integrity and vault structure. Automatically activates when working with Obsidian vaults, markdown notes with wiki-links, or when internal link integrity needs to be preserved during file operations.
|
||||
---
|
||||
|
||||
# Obsidian Vault Manager
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before performing vault operations:
|
||||
|
||||
1. **Verify obsidian-cli is installed:**
|
||||
```bash
|
||||
obsidian-cli --version
|
||||
```
|
||||
|
||||
2. **If obsidian-cli is unavailable:**
|
||||
- Install via: `npm install -g @johnlindquist/obsidian-cli`
|
||||
- Fallback: Standard file operations can be used but will NOT preserve wiki-links
|
||||
- Warning: Without obsidian-cli, moving notes will break all internal `[[wiki-links]]`
|
||||
|
||||
3. **Verify vault is accessible:**
|
||||
```bash
|
||||
obsidian-cli print-default
|
||||
```
|
||||
|
||||
## Overview
|
||||
|
||||
**Use `obsidian-cli` for all Obsidian vault operations.** Standard file tools (mv, Write, Edit) break internal links and ignore vault structure. The `obsidian-cli` tool automatically preserves `[[wiki-links]]` and maintains vault integrity.
|
||||
|
||||
## When to Use
|
||||
|
||||
This skill activates when:
|
||||
- Working with Obsidian vaults (`.md` files with `[[wiki-links]]`)
|
||||
- Moving/renaming notes (links must stay valid)
|
||||
- Creating notes with Obsidian-specific syntax (wiki-links, checkboxes, tags)
|
||||
- Searching vault content or note names
|
||||
- Organizing multiple notes across folders
|
||||
|
||||
**Don't use for:**
|
||||
- General markdown editing outside Obsidian vaults
|
||||
- Static documentation (no internal links)
|
||||
- Single-file markdown operations
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Command | Notes |
|
||||
|------|---------|-------|
|
||||
| Check vault | `obsidian-cli print-default` | Always run first |
|
||||
| Read note | `obsidian-cli print "Note Name"` | Reads by name or path |
|
||||
| Create note | `obsidian-cli create "Name" --content "text"` | Add `--open` to launch Obsidian |
|
||||
| Update note | `obsidian-cli create "Name" --content "text" --append` | Use `--overwrite` to replace |
|
||||
| Move note | `obsidian-cli move "old/path" "new/path"` | **Auto-updates all links** |
|
||||
| Search content | `obsidian-cli search-content "term"` | Searches note contents |
|
||||
| Search names | `obsidian-cli search` | Fuzzy search (interactive) |
|
||||
| Daily note | `obsidian-cli daily` | Create/open today's note |
|
||||
|
||||
**See also:**
|
||||
- [Complete obsidian-cli Command Reference](./references/obsidian-cli-reference.md) - All commands with flags and advanced usage
|
||||
- [Obsidian Syntax Reference](./references/obsidian-syntax.md) - Wiki-links, tags, frontmatter, and markdown syntax
|
||||
- [Note Templates](./assets/templates/) - Daily note, project, and meeting templates
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### Always Check Vault First
|
||||
|
||||
```bash
|
||||
# REQUIRED before any operation
|
||||
obsidian-cli print-default
|
||||
|
||||
# Get path for direct file operations if needed
|
||||
VAULT_PATH=$(obsidian-cli print-default --path-only)
|
||||
```
|
||||
|
||||
**Why:** Paths are vault-relative, not repository-relative. Creating files in wrong location breaks vault structure.
|
||||
|
||||
### Moving/Reorganizing Notes
|
||||
|
||||
```bash
|
||||
# ✅ CORRECT: Auto-updates all links
|
||||
obsidian-cli move "Random Notes/Design" "Projects/Design"
|
||||
|
||||
# ❌ WRONG: Breaks all links to this note
|
||||
mv "vault/Random Notes/Design.md" "vault/Projects/Design.md"
|
||||
```
|
||||
|
||||
**Critical:** `obsidian-cli move` updates every link in the vault automatically. Using `mv` or file operations breaks internal references.
|
||||
|
||||
### Creating/Updating Notes
|
||||
|
||||
```bash
|
||||
# Create new note
|
||||
obsidian-cli create "Projects/Mobile App" --content "# Mobile App\n\n## Tasks\n- [ ] Task 1"
|
||||
|
||||
# Append to existing (safe if file exists)
|
||||
obsidian-cli create "Daily Log" --content "\n## Update\n- New entry" --append
|
||||
|
||||
# Replace existing (use cautiously)
|
||||
obsidian-cli create "Draft" --content "# Fresh content" --overwrite
|
||||
```
|
||||
|
||||
**Obsidian syntax in `--content`:**
|
||||
- Wiki-links: `[[Note Name]]`
|
||||
- Tags: `#project`
|
||||
- Checkboxes: `- [ ] Task`
|
||||
- Newlines: `\n`
|
||||
|
||||
**Templates:** Use provided [note templates](./assets/templates/) as starting points for common note types (daily notes, projects, meetings).
|
||||
|
||||
### Searching and Organizing
|
||||
|
||||
```bash
|
||||
# Find notes mentioning topic
|
||||
obsidian-cli search-content "API design"
|
||||
|
||||
# Read found note
|
||||
obsidian-cli print "Backend/API Design"
|
||||
|
||||
# Reorganize (preserves all links)
|
||||
obsidian-cli move "Backend/API Design" "Projects/Backend/API Design"
|
||||
```
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
| Mistake | Why Wrong | Fix |
|
||||
|---------|-----------|-----|
|
||||
| Using `mv` to move notes | Breaks all `[[wiki-links]]` to that note | Use `obsidian-cli move` |
|
||||
| Using `Write` tool for notes | Creates files outside vault or wrong location | Use `obsidian-cli create --content` |
|
||||
| Using `Read` for vault notes | Misses vault context, no search integration | Use `obsidian-cli print` |
|
||||
| Not checking vault first | Operations fail or create files in wrong place | Always run `print-default` first |
|
||||
| Manual link updating with sed | Error-prone, misses bidirectional links | `obsidian-cli move` handles automatically |
|
||||
| Using absolute paths | Breaks when vault moves | Use vault-relative paths |
|
||||
|
||||
## When to Use Standard Tools
|
||||
|
||||
**Use `obsidian-cli` first.** Only use standard tools when:
|
||||
- Bulk editing note contents (use `Edit` after `obsidian-cli print`)
|
||||
- Complex search patterns (use `Grep` with vault path)
|
||||
- File pattern matching (use `Glob` on `$VAULT_PATH/**/*.md`)
|
||||
|
||||
**Always preserve:**
|
||||
- Frontmatter (YAML between `---`)
|
||||
- Obsidian link syntax `[[Note]]`
|
||||
- Tag syntax `#tag-name`
|
||||
- Markdown structure
|
||||
|
||||
## Integration Pattern
|
||||
|
||||
```bash
|
||||
# 1. Check vault
|
||||
obsidian-cli print-default
|
||||
|
||||
# 2. Use obsidian-cli for vault operations
|
||||
obsidian-cli search-content "search term"
|
||||
obsidian-cli print "Found Note"
|
||||
|
||||
# 3. Use standard tools ONLY when needed
|
||||
# (e.g., complex editing after reading with obsidian-cli)
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
Vault operations succeed when:
|
||||
- All `[[wiki-links]]` remain valid after moves
|
||||
- Notes created in correct vault location
|
||||
- Markdown and frontmatter preserved
|
||||
- Search returns accurate results
|
||||
- No broken links or orphaned notes
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
date: {{date}}
|
||||
tags:
|
||||
- daily-note
|
||||
---
|
||||
|
||||
# {{date}}
|
||||
|
||||
## Morning
|
||||
|
||||
### Goals
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
### Schedule
|
||||
-
|
||||
|
||||
## Notes
|
||||
|
||||
### Meetings
|
||||
|
||||
|
||||
### Ideas
|
||||
|
||||
|
||||
### Quick Captures
|
||||
|
||||
|
||||
## Evening Review
|
||||
|
||||
### Completed
|
||||
-
|
||||
|
||||
### Challenges
|
||||
|
||||
|
||||
### Tomorrow
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
## Links
|
||||
|
||||
- [[{{yesterday}}|Yesterday]]
|
||||
- [[{{tomorrow}}|Tomorrow]]
|
||||
21
skills/obsidian-vault-manager/assets/templates/daily-note.md
Normal file
21
skills/obsidian-vault-manager/assets/templates/daily-note.md
Normal file
@@ -0,0 +1,21 @@
|
||||
---
|
||||
date: {{date:YYYY-MM-DD}}
|
||||
tags: [daily-note]
|
||||
---
|
||||
|
||||
# {{date:YYYY-MM-DD}}
|
||||
|
||||
## 📝 Today's Focus
|
||||
|
||||
- [ ]
|
||||
|
||||
## ✅ Completed
|
||||
|
||||
-
|
||||
|
||||
## 💭 Notes
|
||||
|
||||
## 🔗 Links
|
||||
|
||||
- [[Yesterday|{{date-1d:YYYY-MM-DD}}]]
|
||||
- [[Tomorrow|{{date+1d:YYYY-MM-DD}}]]
|
||||
@@ -0,0 +1,71 @@
|
||||
---
|
||||
title: "{{meeting-title}}"
|
||||
date: {{date}}
|
||||
time: {{time}}
|
||||
tags:
|
||||
- meeting
|
||||
- {{tag}}
|
||||
attendees:
|
||||
- {{attendee}}
|
||||
---
|
||||
|
||||
# {{meeting-title}}
|
||||
|
||||
**Date:** {{date}}
|
||||
**Time:** {{time}}
|
||||
**Location:**
|
||||
|
||||
## Attendees
|
||||
|
||||
- [[{{attendee-1}}]]
|
||||
- [[{{attendee-2}}]]
|
||||
|
||||
## Agenda
|
||||
|
||||
1.
|
||||
2.
|
||||
3.
|
||||
|
||||
## Discussion
|
||||
|
||||
### Topic 1
|
||||
|
||||
|
||||
### Topic 2
|
||||
|
||||
|
||||
### Topic 3
|
||||
|
||||
|
||||
## Decisions
|
||||
|
||||
-
|
||||
|
||||
## Action Items
|
||||
|
||||
- [ ] {{person}} - {{action}} - Due: {{date}}
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
## Parking Lot
|
||||
|
||||
-
|
||||
|
||||
## Next Steps
|
||||
|
||||
|
||||
|
||||
## Follow-up
|
||||
|
||||
**Next Meeting:** {{date}}
|
||||
|
||||
## Links
|
||||
|
||||
- [[{{previous-meeting}}|Previous Meeting]]
|
||||
- [[{{project}}|Project]]
|
||||
-
|
||||
|
||||
---
|
||||
|
||||
**Notes by:**
|
||||
**Distribution:**
|
||||
40
skills/obsidian-vault-manager/assets/templates/meeting.md
Normal file
40
skills/obsidian-vault-manager/assets/templates/meeting.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
date: {{date:YYYY-MM-DD}}
|
||||
tags: [meeting]
|
||||
attendees: []
|
||||
---
|
||||
|
||||
# {{title}} - {{date:YYYY-MM-DD}}
|
||||
|
||||
## 📅 Meeting Info
|
||||
|
||||
- **Date:** {{date:YYYY-MM-DD HH:mm}}
|
||||
- **Attendees:**
|
||||
-
|
||||
- **Location:**
|
||||
|
||||
## 📋 Agenda
|
||||
|
||||
1.
|
||||
2.
|
||||
3.
|
||||
|
||||
## 📝 Notes
|
||||
|
||||
### Topic 1
|
||||
|
||||
### Topic 2
|
||||
|
||||
## ✅ Action Items
|
||||
|
||||
- [ ] [@person] Action item 1
|
||||
- [ ] [@person] Action item 2
|
||||
|
||||
## 🔗 Related
|
||||
|
||||
- [[Previous Meeting|{{date-7d:YYYY-MM-DD}}]]
|
||||
- [[Project Name]]
|
||||
|
||||
## 📄 Attachments
|
||||
|
||||
-
|
||||
@@ -0,0 +1,94 @@
|
||||
---
|
||||
title: {{project-name}}
|
||||
status: planning
|
||||
start-date: {{date}}
|
||||
tags:
|
||||
- project
|
||||
- {{tag}}
|
||||
---
|
||||
|
||||
# {{project-name}}
|
||||
|
||||
## Overview
|
||||
|
||||
**Status:** #status/planning
|
||||
**Owner:**
|
||||
**Timeline:**
|
||||
|
||||
### Goals
|
||||
|
||||
|
||||
|
||||
### Success Criteria
|
||||
|
||||
|
||||
|
||||
## Context
|
||||
|
||||
### Problem Statement
|
||||
|
||||
|
||||
### Background
|
||||
|
||||
|
||||
## Plan
|
||||
|
||||
### Phases
|
||||
|
||||
- [ ] Phase 1:
|
||||
- [ ] Phase 2:
|
||||
- [ ] Phase 3:
|
||||
|
||||
### Milestones
|
||||
|
||||
| Milestone | Target Date | Status |
|
||||
| --------- | ----------- | ------ |
|
||||
| | | |
|
||||
|
||||
## Tasks
|
||||
|
||||
### To Do
|
||||
- [ ]
|
||||
- [ ]
|
||||
- [ ]
|
||||
|
||||
### In Progress
|
||||
-
|
||||
|
||||
### Completed
|
||||
- [x]
|
||||
|
||||
### Blocked
|
||||
-
|
||||
|
||||
## Resources
|
||||
|
||||
### Documents
|
||||
- [[]]
|
||||
|
||||
### References
|
||||
-
|
||||
|
||||
### Team
|
||||
-
|
||||
|
||||
## Notes
|
||||
|
||||
### Decisions
|
||||
|
||||
|
||||
### Risks
|
||||
|
||||
|
||||
### Open Questions
|
||||
- [ ]
|
||||
|
||||
## Updates
|
||||
|
||||
### {{date}}
|
||||
|
||||
|
||||
## Related
|
||||
|
||||
- [[Projects MOC]]
|
||||
-
|
||||
48
skills/obsidian-vault-manager/assets/templates/project.md
Normal file
48
skills/obsidian-vault-manager/assets/templates/project.md
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: {{title}}
|
||||
tags: [project]
|
||||
status: planning
|
||||
created: {{date:YYYY-MM-DD}}
|
||||
---
|
||||
|
||||
# {{title}}
|
||||
|
||||
## 🎯 Overview
|
||||
|
||||
Brief description of the project.
|
||||
|
||||
## 📋 Goals
|
||||
|
||||
- [ ] Goal 1
|
||||
- [ ] Goal 2
|
||||
- [ ] Goal 3
|
||||
|
||||
## ✅ Tasks
|
||||
|
||||
### To Do
|
||||
|
||||
- [ ] Task 1
|
||||
- [ ] Task 2
|
||||
|
||||
### In Progress
|
||||
|
||||
-
|
||||
|
||||
### Done
|
||||
|
||||
-
|
||||
|
||||
## 📚 Resources
|
||||
|
||||
- [[Link to related note]]
|
||||
-
|
||||
|
||||
## 📝 Notes
|
||||
|
||||
### {{date:YYYY-MM-DD}}
|
||||
|
||||
Initial project setup.
|
||||
|
||||
## 🏷️ Related Projects
|
||||
|
||||
- [[Related Project 1]]
|
||||
@@ -0,0 +1,380 @@
|
||||
# obsidian-cli Command Reference
|
||||
|
||||
Complete reference for `obsidian-cli` commands and advanced usage patterns.
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
npm install -g @johnlindquist/obsidian-cli
|
||||
```
|
||||
|
||||
Verify installation:
|
||||
```bash
|
||||
obsidian-cli --version
|
||||
```
|
||||
|
||||
## Core Commands
|
||||
|
||||
### print-default
|
||||
|
||||
Display current vault information.
|
||||
|
||||
```bash
|
||||
obsidian-cli print-default
|
||||
```
|
||||
|
||||
**Flags:**
|
||||
- `--path-only` - Output only the vault path (useful for scripting)
|
||||
|
||||
**Output:**
|
||||
- Vault name
|
||||
- Vault path
|
||||
- Vault status
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
# Get vault info
|
||||
obsidian-cli print-default
|
||||
|
||||
# Get path for scripts
|
||||
VAULT_PATH=$(obsidian-cli print-default --path-only)
|
||||
echo "Vault location: $VAULT_PATH"
|
||||
```
|
||||
|
||||
### print
|
||||
|
||||
Read note contents by name or path.
|
||||
|
||||
```bash
|
||||
obsidian-cli print "Note Name"
|
||||
obsidian-cli print "folder/Note Name"
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
- Searches by note name first (without path)
|
||||
- Falls back to path-based lookup
|
||||
- Returns full note contents including frontmatter
|
||||
- Case-sensitive matching
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Read by name
|
||||
obsidian-cli print "Project Plan"
|
||||
|
||||
# Read by path
|
||||
obsidian-cli print "Work/Projects/Project Plan"
|
||||
|
||||
# Pipe to other tools
|
||||
obsidian-cli print "Note" | grep "TODO"
|
||||
```
|
||||
|
||||
### create
|
||||
|
||||
Create new notes or update existing ones.
|
||||
|
||||
```bash
|
||||
obsidian-cli create "Note Name" --content "content"
|
||||
```
|
||||
|
||||
**Required Flags:**
|
||||
- `--content "text"` - Note content (supports `\n` for newlines)
|
||||
|
||||
**Optional Flags:**
|
||||
- `--append` - Add content to end of existing note (safe for existing files)
|
||||
- `--overwrite` - Replace entire note (destructive)
|
||||
- `--open` - Open note in Obsidian after creation
|
||||
|
||||
**Content Syntax:**
|
||||
- Use `\n` for newlines
|
||||
- Include Obsidian syntax: `[[wiki-links]]`, `#tags`, `- [ ]` checkboxes
|
||||
- Frontmatter can be included in content
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Create new note
|
||||
obsidian-cli create "Meeting Notes" --content "# Meeting\n\nAttendees: [[John]], [[Sarah]]"
|
||||
|
||||
# Append to existing
|
||||
obsidian-cli create "Daily Log" --content "\n## 3pm Update\n- Completed task" --append
|
||||
|
||||
# Replace existing (caution!)
|
||||
obsidian-cli create "Draft" --content "# New Draft\n\nStarting over" --overwrite
|
||||
|
||||
# Create and open in Obsidian
|
||||
obsidian-cli create "Quick Note" --content "# Note" --open
|
||||
```
|
||||
|
||||
**Frontmatter Example:**
|
||||
```bash
|
||||
obsidian-cli create "Book Review" --content "---\ntitle: Book Title\nauthor: Author Name\nrating: 5\n---\n\n# Review\n\nExcellent book about [[Topic]]"
|
||||
```
|
||||
|
||||
### move
|
||||
|
||||
Move or rename notes while preserving all wiki-links.
|
||||
|
||||
```bash
|
||||
obsidian-cli move "old/path" "new/path"
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
- Automatically updates ALL links to moved note throughout entire vault
|
||||
- Updates bidirectional links
|
||||
- Maintains frontmatter and note content
|
||||
- Creates destination folder if needed
|
||||
|
||||
**Path Formats:**
|
||||
- Vault-relative paths (no leading `/`)
|
||||
- With or without `.md` extension
|
||||
- Folder paths for organizing
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Move note to different folder
|
||||
obsidian-cli move "Inbox/Idea" "Projects/New Idea"
|
||||
|
||||
# Rename note
|
||||
obsidian-cli move "Draft Title" "Final Title"
|
||||
|
||||
# Reorganize with folders
|
||||
obsidian-cli move "Random/Design Doc" "Projects/Mobile/Design Doc"
|
||||
|
||||
# Move with .md extension (works the same)
|
||||
obsidian-cli move "note.md" "folder/note.md"
|
||||
```
|
||||
|
||||
**Critical:** This is the ONLY safe way to move notes. Using `mv`, `Write`, or file operations will break all links.
|
||||
|
||||
### search-content
|
||||
|
||||
Search note contents for text.
|
||||
|
||||
```bash
|
||||
obsidian-cli search-content "search term"
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
- Full-text search across all notes
|
||||
- Returns matching note paths
|
||||
- Case-insensitive by default
|
||||
- Searches note content, not just titles
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Find notes about a topic
|
||||
obsidian-cli search-content "API design"
|
||||
|
||||
# Find todos
|
||||
obsidian-cli search-content "- [ ]"
|
||||
|
||||
# Find tagged notes
|
||||
obsidian-cli search-content "#important"
|
||||
|
||||
# Combine with other commands
|
||||
for note in $(obsidian-cli search-content "refactor"); do
|
||||
echo "Found in: $note"
|
||||
obsidian-cli print "$note"
|
||||
done
|
||||
```
|
||||
|
||||
### search
|
||||
|
||||
Interactive fuzzy search for note names.
|
||||
|
||||
```bash
|
||||
obsidian-cli search
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
- Opens interactive picker
|
||||
- Fuzzy matching on note names
|
||||
- Navigate with arrow keys
|
||||
- Press Enter to select
|
||||
|
||||
**Usage:**
|
||||
- Run command
|
||||
- Type to filter notes
|
||||
- Select note with Enter
|
||||
- Use selected note path in scripts
|
||||
|
||||
**Note:** This is interactive and may not work in all automation contexts. Use `search-content` for scripting.
|
||||
|
||||
### daily
|
||||
|
||||
Create or open daily note.
|
||||
|
||||
```bash
|
||||
obsidian-cli daily
|
||||
```
|
||||
|
||||
**Behavior:**
|
||||
- Creates note with today's date (YYYY-MM-DD format by default)
|
||||
- Opens in Obsidian if it already exists
|
||||
- Uses vault's daily note template if configured
|
||||
|
||||
**Examples:**
|
||||
```bash
|
||||
# Open today's note
|
||||
obsidian-cli daily
|
||||
|
||||
# Create with custom content
|
||||
obsidian-cli daily && obsidian-cli create "$(date +%Y-%m-%d)" --content "\n## Evening Review\n- Accomplishments" --append
|
||||
```
|
||||
|
||||
## Advanced Usage Patterns
|
||||
|
||||
### Scripting with obsidian-cli
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# Get vault path for reference
|
||||
VAULT_PATH=$(obsidian-cli print-default --path-only)
|
||||
|
||||
# Search and process notes
|
||||
obsidian-cli search-content "TODO" | while read -r note; do
|
||||
echo "Processing: $note"
|
||||
content=$(obsidian-cli print "$note")
|
||||
# Process content...
|
||||
done
|
||||
|
||||
# Bulk reorganization
|
||||
for note in $(obsidian-cli search-content "#archive"); do
|
||||
obsidian-cli move "$note" "Archive/$note"
|
||||
done
|
||||
```
|
||||
|
||||
### Combining with Standard Tools
|
||||
|
||||
```bash
|
||||
# Use obsidian-cli for vault operations, then standard tools for processing
|
||||
obsidian-cli print "Note" > /tmp/note.md
|
||||
# Edit with standard tools
|
||||
sed -i 's/old/new/g' /tmp/note.md
|
||||
# Write back to vault
|
||||
obsidian-cli create "Note" --content "$(cat /tmp/note.md)" --overwrite
|
||||
```
|
||||
|
||||
### Template-Based Note Creation
|
||||
|
||||
```bash
|
||||
# Read template
|
||||
TEMPLATE=$(cat templates/project-template.md)
|
||||
|
||||
# Create note with template
|
||||
obsidian-cli create "New Project" --content "$TEMPLATE"
|
||||
|
||||
# Create with substitutions
|
||||
TEMPLATE=$(cat templates/meeting-template.md | sed "s/DATE/$(date +%Y-%m-%d)/g")
|
||||
obsidian-cli create "Meeting - Team Sync" --content "$TEMPLATE"
|
||||
```
|
||||
|
||||
### Batch Operations
|
||||
|
||||
```bash
|
||||
# Rename multiple notes with pattern
|
||||
for note in Project-*; do
|
||||
new_name=$(echo "$note" | sed 's/Project-/Archived-Project-/')
|
||||
obsidian-cli move "$note" "Archive/$new_name"
|
||||
done
|
||||
|
||||
# Add tag to multiple notes
|
||||
obsidian-cli search-content "machine learning" | while read -r note; do
|
||||
content=$(obsidian-cli print "$note")
|
||||
obsidian-cli create "$note" --content "$content\n\n#machine-learning" --append
|
||||
done
|
||||
```
|
||||
|
||||
### Working with Frontmatter
|
||||
|
||||
```bash
|
||||
# Create note with complex frontmatter
|
||||
obsidian-cli create "Article" --content "---
|
||||
title: Article Title
|
||||
date: $(date +%Y-%m-%d)
|
||||
tags:
|
||||
- article
|
||||
- published
|
||||
author: John Doe
|
||||
---
|
||||
|
||||
# Article Title
|
||||
|
||||
Content here with [[Wiki Links]]"
|
||||
```
|
||||
|
||||
### Link Integrity Verification
|
||||
|
||||
```bash
|
||||
# After bulk operations, verify links
|
||||
# (obsidian-cli handles this automatically, but for validation:)
|
||||
VAULT_PATH=$(obsidian-cli print-default --path-only)
|
||||
|
||||
# Use standard tools to find broken links
|
||||
grep -r "\[\[.*\]\]" "$VAULT_PATH" | while read -r line; do
|
||||
# Check if target exists
|
||||
# obsidian-cli move ensures this isn't needed
|
||||
done
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Command Not Found
|
||||
|
||||
```bash
|
||||
# Install globally
|
||||
npm install -g @johnlindquist/obsidian-cli
|
||||
|
||||
# Or use npx
|
||||
npx @johnlindquist/obsidian-cli print-default
|
||||
```
|
||||
|
||||
### No Default Vault
|
||||
|
||||
Error: "No default vault set"
|
||||
|
||||
**Solution:**
|
||||
- Open Obsidian application
|
||||
- Vault must be opened at least once
|
||||
- obsidian-cli reads from Obsidian's configuration
|
||||
|
||||
### Path Issues
|
||||
|
||||
**Problem:** Note not found by name
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Use full path
|
||||
obsidian-cli print "folder/subfolder/Note Name"
|
||||
|
||||
# Or search first
|
||||
obsidian-cli search-content "unique phrase in note"
|
||||
```
|
||||
|
||||
### Newlines Not Working
|
||||
|
||||
**Problem:** `\n` appears literally in notes
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Use echo with -e flag
|
||||
obsidian-cli create "Note" --content "$(echo -e "Line 1\nLine 2")"
|
||||
|
||||
# Or use $'...' syntax
|
||||
obsidian-cli create "Note" --content $'Line 1\nLine 2'
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always check vault first:** Run `print-default` before operations
|
||||
2. **Use obsidian-cli move exclusively:** Never use `mv` for notes
|
||||
3. **Preserve Obsidian syntax:** Maintain `[[links]]`, `#tags`, frontmatter
|
||||
4. **Test on copies:** For bulk operations, test on duplicate notes first
|
||||
5. **Use --append safely:** Append is safe for existing files, overwrite is destructive
|
||||
6. **Script defensively:** Check command success before proceeding
|
||||
7. **Backup regularly:** obsidian-cli is safe, but backups prevent mistakes
|
||||
|
||||
## See Also
|
||||
|
||||
- [Obsidian Syntax Reference](./obsidian-syntax.md) - Wiki-link and markdown syntax
|
||||
- [Note Templates](../assets/templates/) - Ready-to-use note templates
|
||||
567
skills/obsidian-vault-manager/references/obsidian-syntax.md
Normal file
567
skills/obsidian-vault-manager/references/obsidian-syntax.md
Normal file
@@ -0,0 +1,567 @@
|
||||
# Obsidian Markdown Syntax Reference
|
||||
|
||||
Complete reference for Obsidian-specific markdown syntax, including wiki-links, tags, frontmatter, and extended markdown features.
|
||||
|
||||
## Wiki-Links
|
||||
|
||||
Obsidian's primary linking syntax for internal note connections.
|
||||
|
||||
### Basic Wiki-Links
|
||||
|
||||
```markdown
|
||||
[[Note Name]]
|
||||
```
|
||||
|
||||
Links to a note named "Note Name.md" anywhere in the vault.
|
||||
|
||||
**Characteristics:**
|
||||
- Case-sensitive
|
||||
- Extension not required
|
||||
- Searches entire vault by name
|
||||
- Creates link even if note doesn't exist (shown in different color in Obsidian)
|
||||
|
||||
### Wiki-Links with Aliases
|
||||
|
||||
```markdown
|
||||
[[Actual Note Name|Display Text]]
|
||||
```
|
||||
|
||||
Display custom text while linking to the actual note.
|
||||
|
||||
**Examples:**
|
||||
```markdown
|
||||
See the [[Project Requirements|requirements]] for details.
|
||||
Read [[Albert Einstein|Einstein's]] biography.
|
||||
Check [[2024-01-15|yesterday's notes]].
|
||||
```
|
||||
|
||||
### Wiki-Links to Headings
|
||||
|
||||
```markdown
|
||||
[[Note Name#Heading]]
|
||||
[[Note Name#Heading|Custom Text]]
|
||||
```
|
||||
|
||||
Link to specific section within a note.
|
||||
|
||||
**Examples:**
|
||||
```markdown
|
||||
Review [[Meeting Notes#Action Items]]
|
||||
See [[API Documentation#Authentication|auth docs]]
|
||||
```
|
||||
|
||||
**Heading Link Rules:**
|
||||
- Heading text must match exactly (case-sensitive)
|
||||
- Use heading text without the `#` prefix
|
||||
- Spaces in headings are preserved
|
||||
- Works with any heading level
|
||||
|
||||
### Wiki-Links to Blocks
|
||||
|
||||
```markdown
|
||||
[[Note Name#^block-id]]
|
||||
```
|
||||
|
||||
Link to specific block within a note.
|
||||
|
||||
**Block ID Syntax:**
|
||||
```markdown
|
||||
This is a paragraph with an ID. ^block-123
|
||||
|
||||
- List item with ID ^item-456
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
Reference: [[Research#^key-finding]]
|
||||
```
|
||||
|
||||
### Wiki-Links with Paths
|
||||
|
||||
```markdown
|
||||
[[folder/subfolder/Note Name]]
|
||||
```
|
||||
|
||||
Specify path when multiple notes share the same name.
|
||||
|
||||
**Examples:**
|
||||
```markdown
|
||||
[[Work/Projects/Project Plan]]
|
||||
[[Personal/Projects/Project Plan]]
|
||||
```
|
||||
|
||||
### Embedding Notes
|
||||
|
||||
```markdown
|
||||
![[Note Name]]
|
||||
```
|
||||
|
||||
Embed the entire content of another note.
|
||||
|
||||
**Examples:**
|
||||
```markdown
|
||||
![[Meeting Template]]
|
||||
![[Quote Collection#Favorite Quotes]]
|
||||
```
|
||||
|
||||
### Embedding Images
|
||||
|
||||
```markdown
|
||||
![[image.png]]
|
||||
![[image.png|200]]
|
||||
![[image.png|200x100]]
|
||||
![[folder/image.png|Custom Alt Text|300]]
|
||||
```
|
||||
|
||||
**Size Specifications:**
|
||||
- `|width` - Set width, maintain aspect ratio
|
||||
- `|widthxheight` - Set both dimensions
|
||||
- Add alt text before dimensions
|
||||
|
||||
## Tags
|
||||
|
||||
Flexible categorization and filtering system.
|
||||
|
||||
### Basic Tags
|
||||
|
||||
```markdown
|
||||
#tag
|
||||
#tag-name
|
||||
#tag_name
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Start with `#`
|
||||
- No spaces (use `-` or `_`)
|
||||
- Alphanumeric characters
|
||||
- Case-sensitive
|
||||
- Can appear anywhere in note
|
||||
|
||||
**Examples:**
|
||||
```markdown
|
||||
#project #work #important
|
||||
|
||||
This note is about #machine-learning concepts.
|
||||
|
||||
Status: #in-progress
|
||||
```
|
||||
|
||||
### Nested Tags
|
||||
|
||||
```markdown
|
||||
#parent/child
|
||||
#parent/child/grandchild
|
||||
```
|
||||
|
||||
Creates tag hierarchy.
|
||||
|
||||
**Examples:**
|
||||
```markdown
|
||||
#project/work/client-a
|
||||
#project/personal/side-hustle
|
||||
#status/active
|
||||
#status/archived
|
||||
```
|
||||
|
||||
**In Obsidian UI:**
|
||||
- Tags displayed as hierarchy
|
||||
- Filter by parent shows all children
|
||||
- Organize tags logically
|
||||
|
||||
### Inline Tags
|
||||
|
||||
Tags can appear anywhere in text:
|
||||
|
||||
```markdown
|
||||
Discussed #meeting-notes with team about #q1-planning.
|
||||
|
||||
#review-required
|
||||
```
|
||||
|
||||
### Multi-Word Tags
|
||||
|
||||
```markdown
|
||||
#multi-word-tag
|
||||
#multi_word_tag
|
||||
```
|
||||
|
||||
Use hyphens or underscores, not spaces.
|
||||
|
||||
## Frontmatter (YAML)
|
||||
|
||||
Structured metadata at the start of notes.
|
||||
|
||||
### Basic Frontmatter
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: Note Title
|
||||
author: Author Name
|
||||
date: 2024-01-15
|
||||
---
|
||||
|
||||
# Note Content
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Must be at very start of file
|
||||
- Enclosed in `---` delimiters
|
||||
- YAML syntax
|
||||
- Key-value pairs
|
||||
|
||||
### Common Fields
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: Document Title
|
||||
date: 2024-01-15
|
||||
tags:
|
||||
- tag1
|
||||
- tag2
|
||||
aliases:
|
||||
- Alternative Name
|
||||
- Shorthand
|
||||
author: John Doe
|
||||
status: draft
|
||||
---
|
||||
```
|
||||
|
||||
### Array Values
|
||||
|
||||
```markdown
|
||||
---
|
||||
tags:
|
||||
- project
|
||||
- important
|
||||
categories: [work, planning]
|
||||
---
|
||||
```
|
||||
|
||||
Both syntaxes work (YAML list or inline array).
|
||||
|
||||
### Nested Objects
|
||||
|
||||
```markdown
|
||||
---
|
||||
metadata:
|
||||
created: 2024-01-15
|
||||
modified: 2024-01-20
|
||||
version: 1.2
|
||||
project:
|
||||
name: Project Alpha
|
||||
status: active
|
||||
team:
|
||||
- Alice
|
||||
- Bob
|
||||
---
|
||||
```
|
||||
|
||||
### Obsidian-Specific Fields
|
||||
|
||||
```markdown
|
||||
---
|
||||
aliases:
|
||||
- Alt Name 1
|
||||
- Alt Name 2
|
||||
tags:
|
||||
- vault-tag
|
||||
cssclasses:
|
||||
- custom-theme
|
||||
- wide-page
|
||||
---
|
||||
```
|
||||
|
||||
**Special Fields:**
|
||||
- `aliases` - Alternative names for wiki-links
|
||||
- `tags` - Tags (alternative to inline `#tags`)
|
||||
- `cssclasses` - Custom CSS classes for styling
|
||||
|
||||
## Task Lists (Checkboxes)
|
||||
|
||||
Extended checkbox syntax beyond standard markdown.
|
||||
|
||||
### Standard Checkboxes
|
||||
|
||||
```markdown
|
||||
- [ ] Unchecked task
|
||||
- [x] Completed task
|
||||
- [X] Completed task (capital X works too)
|
||||
```
|
||||
|
||||
### Extended Checkbox Types
|
||||
|
||||
```markdown
|
||||
- [ ] To do
|
||||
- [x] Done
|
||||
- [>] Forwarded/Rescheduled
|
||||
- [<] Scheduled
|
||||
- [-] Cancelled
|
||||
- [?] Question
|
||||
- [!] Important
|
||||
- [*] Star
|
||||
- ["] Quote
|
||||
- [l] Location
|
||||
- [b] Bookmark
|
||||
- [i] Information
|
||||
- [S] Amount/Money
|
||||
- [I] Idea
|
||||
- [p] Pro
|
||||
- [c] Con
|
||||
- [f] Fire
|
||||
- [k] Key
|
||||
- [w] Win
|
||||
- [u] Up
|
||||
- [d] Down
|
||||
```
|
||||
|
||||
**Note:** Extended types require Obsidian or plugins. Rendered specially in Obsidian UI.
|
||||
|
||||
### Nested Tasks
|
||||
|
||||
```markdown
|
||||
- [ ] Parent task
|
||||
- [ ] Subtask 1
|
||||
- [x] Subtask 2
|
||||
- [ ] Subtask 3
|
||||
- [ ] Sub-subtask
|
||||
```
|
||||
|
||||
## Callouts (Admonitions)
|
||||
|
||||
Styled information blocks.
|
||||
|
||||
### Basic Callout
|
||||
|
||||
```markdown
|
||||
> [!note]
|
||||
> This is a note callout.
|
||||
|
||||
> [!info]
|
||||
> This is an info callout.
|
||||
```
|
||||
|
||||
### Callout Types
|
||||
|
||||
```markdown
|
||||
> [!note]
|
||||
> Note content
|
||||
|
||||
> [!abstract] / [!summary] / [!tldr]
|
||||
> Summary content
|
||||
|
||||
> [!info] / [!todo]
|
||||
> Information
|
||||
|
||||
> [!tip] / [!hint] / [!important]
|
||||
> Helpful tip
|
||||
|
||||
> [!success] / [!check] / [!done]
|
||||
> Success message
|
||||
|
||||
> [!question] / [!help] / [!faq]
|
||||
> Question content
|
||||
|
||||
> [!warning] / [!caution] / [!attention]
|
||||
> Warning message
|
||||
|
||||
> [!failure] / [!fail] / [!missing]
|
||||
> Error message
|
||||
|
||||
> [!danger] / [!error]
|
||||
> Danger warning
|
||||
|
||||
> [!bug]
|
||||
> Bug report
|
||||
|
||||
> [!example]
|
||||
> Example content
|
||||
|
||||
> [!quote] / [!cite]
|
||||
> Quoted text
|
||||
```
|
||||
|
||||
### Callout with Title
|
||||
|
||||
```markdown
|
||||
> [!note] Custom Title
|
||||
> Content goes here.
|
||||
|
||||
> [!warning] Important Warning
|
||||
> This is critical information.
|
||||
```
|
||||
|
||||
### Foldable Callouts
|
||||
|
||||
```markdown
|
||||
> [!note]- Collapsed by default
|
||||
> Content hidden initially.
|
||||
|
||||
> [!note]+ Expanded by default
|
||||
> Content visible initially.
|
||||
```
|
||||
|
||||
### Nested Callouts
|
||||
|
||||
```markdown
|
||||
> [!info] Outer callout
|
||||
> Information here.
|
||||
>
|
||||
> > [!warning] Nested callout
|
||||
> > Nested warning.
|
||||
```
|
||||
|
||||
## Code Blocks
|
||||
|
||||
### Basic Code Blocks
|
||||
|
||||
````markdown
|
||||
```
|
||||
Plain code block
|
||||
```
|
||||
|
||||
```javascript
|
||||
console.log("JavaScript code");
|
||||
```
|
||||
|
||||
```python
|
||||
print("Python code")
|
||||
```
|
||||
````
|
||||
|
||||
### With Line Numbers
|
||||
|
||||
Obsidian doesn't natively support line numbers, but some plugins do.
|
||||
|
||||
## Tables
|
||||
|
||||
### Basic Tables
|
||||
|
||||
```markdown
|
||||
| Column 1 | Column 2 | Column 3 |
|
||||
| -------- | -------- | -------- |
|
||||
| Row 1 | Data | Data |
|
||||
| Row 2 | Data | Data |
|
||||
```
|
||||
|
||||
### Alignment
|
||||
|
||||
```markdown
|
||||
| Left | Center | Right |
|
||||
| :--- | :----: | ----: |
|
||||
| L1 | C1 | R1 |
|
||||
| L2 | C2 | R2 |
|
||||
```
|
||||
|
||||
### Tables with Links
|
||||
|
||||
```markdown
|
||||
| Project | Status | Notes |
|
||||
| ------- | ------ | ----- |
|
||||
| [[Project A]] | #active | See [[Notes]] |
|
||||
| [[Project B]] | #done | Complete |
|
||||
```
|
||||
|
||||
## Comments
|
||||
|
||||
```markdown
|
||||
%%
|
||||
This is a comment.
|
||||
Multi-line comments are supported.
|
||||
%%
|
||||
|
||||
Regular text. %% Inline comment %%
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Enclosed in `%%`
|
||||
- Not rendered in reading view
|
||||
- Can be inline or multi-line
|
||||
|
||||
## Footnotes
|
||||
|
||||
```markdown
|
||||
Here's a sentence with a footnote[^1].
|
||||
|
||||
[^1]: This is the footnote content.
|
||||
|
||||
Another reference[^note].
|
||||
|
||||
[^note]: Named footnotes work too.
|
||||
```
|
||||
|
||||
## Obsidian URI
|
||||
|
||||
Link to open notes in Obsidian app:
|
||||
|
||||
```markdown
|
||||
obsidian://open?vault=VaultName&file=NoteName
|
||||
|
||||
[Open Note](obsidian://open?vault=MyVault&file=folder/note)
|
||||
```
|
||||
|
||||
## Combining Syntax
|
||||
|
||||
### Complex Examples
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: Project Plan
|
||||
tags:
|
||||
- project
|
||||
- planning
|
||||
status: active
|
||||
---
|
||||
|
||||
# [[Projects|Project]]: Mobile App Redesign
|
||||
|
||||
## Overview
|
||||
|
||||
This project focuses on #ui-ux improvements. See [[Design System]] for details.
|
||||
|
||||
## Tasks
|
||||
|
||||
- [ ] Review [[Requirements#Functional|functional requirements]]
|
||||
- [x] Create [[Wireframes]]
|
||||
- [>] Schedule meeting with #stakeholders
|
||||
- [ ] Update [[Project Timeline]]
|
||||
|
||||
## References
|
||||
|
||||
![[Design Principles#Core Values]]
|
||||
|
||||
> [!tip] Best Practice
|
||||
> Always link to [[Style Guide]] when implementing designs.
|
||||
|
||||
## Related
|
||||
|
||||
- [[Previous Projects#Mobile|Past mobile work]]
|
||||
- [[Team Members|Team]]
|
||||
|
||||
#project/mobile #status/in-progress
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use wiki-links liberally** - Create connections between related notes
|
||||
2. **Consistent tag hierarchy** - Use nested tags for organization (`#project/work/client`)
|
||||
3. **Frontmatter for metadata** - Structure data that's queried frequently
|
||||
4. **Aliases for flexibility** - Add aliases for common alternative names
|
||||
5. **Descriptive link text** - Use aliases when natural reading flow matters
|
||||
6. **Block links sparingly** - For specific references within longer notes
|
||||
7. **Comments for drafts** - Use `%%` for notes to self that shouldn't be published
|
||||
8. **Callouts for emphasis** - Highlight important information visually
|
||||
|
||||
## Compatibility Notes
|
||||
|
||||
- Standard markdown works everywhere
|
||||
- Wiki-links are Obsidian-specific (convert to regular links for export)
|
||||
- Extended checkboxes may need plugins outside Obsidian
|
||||
- Callouts are Obsidian-specific (render as blockquotes elsewhere)
|
||||
- Frontmatter is standard YAML (works in most markdown processors)
|
||||
- Comments (`%%`) are Obsidian-specific
|
||||
- Tags work in Obsidian; may be ignored elsewhere
|
||||
|
||||
## See Also
|
||||
|
||||
- [obsidian-cli Reference](./obsidian-cli-reference.md) - Command-line vault operations
|
||||
- [Note Templates](../assets/templates/) - Ready-to-use note structures
|
||||
319
skills/technical-writer/SKILL.md
Normal file
319
skills/technical-writer/SKILL.md
Normal file
@@ -0,0 +1,319 @@
|
||||
---
|
||||
name: technical-writer
|
||||
description: Expert in technical documentation (README, API docs, guides, tutorials, quickstarts, specs, release notes) that automatically activates when creating, editing, or reviewing .md files in docs/ directories, README files, or when discussing documentation structure, style guides, or content organization. Follows industry best practices for clear, accessible technical communication across all documentation types.
|
||||
---
|
||||
|
||||
# Technical Documentation Expert
|
||||
|
||||
## Overview
|
||||
|
||||
Provides expert guidance for creating clear, comprehensive, and user-friendly technical documentation following industry best practices and structured content models.
|
||||
|
||||
**Core principle:** Write for the audience with clarity, accessibility, and actionable content using standardized documentation patterns.
|
||||
|
||||
## When to Use
|
||||
|
||||
Automatically activates when:
|
||||
|
||||
- Working with `.md` files in `docs/` directories
|
||||
- Creating or editing README files
|
||||
- Editing documentation files or markup
|
||||
- Discussing documentation structure, information architecture, or style guides
|
||||
- Creating API documentation with examples and parameter tables
|
||||
- Writing user guides, tutorials, or quickstarts
|
||||
- Drafting release notes or change logs
|
||||
- Structuring specifications or technical proposals
|
||||
|
||||
Manual invocation when:
|
||||
|
||||
- User explicitly asks about documentation best practices
|
||||
- User needs guidance on content organization or structure
|
||||
- User requests help with technical writing style
|
||||
- User encounters documentation quality issues
|
||||
|
||||
## When NOT to Use This Skill
|
||||
|
||||
Do not use this skill for:
|
||||
|
||||
- Creative writing or marketing copy
|
||||
- Code implementation (documentation only)
|
||||
- Project management documentation
|
||||
- Internal team chat or informal notes
|
||||
- Academic papers or research documentation
|
||||
|
||||
## Core Expertise Areas
|
||||
|
||||
### Content Types
|
||||
|
||||
1. **Conceptual** - Explains what something is and why it's useful ("About..." articles)
|
||||
2. **Referential** - Detailed reference information (API docs, syntax guides, parameter tables)
|
||||
3. **Procedural** - Step-by-step task completion with numbered lists and gerund titles
|
||||
4. **Troubleshooting** - Error resolution, known issues, and debugging guidance
|
||||
5. **Quickstart** - Essential setup in 5 minutes/600 words maximum
|
||||
6. **Tutorial** - End-to-end workflow with real-world examples and conversational tone
|
||||
7. **Release Notes** - Version changes categorized by type (Features, Fixes, Breaking Changes)
|
||||
|
||||
### Documentation Structure
|
||||
|
||||
**Standard Article Elements:**
|
||||
|
||||
- Titles: Sentence case, gerund for procedures, character limits by level
|
||||
- Intros: 1-2 sentences explaining content
|
||||
- Prerequisites and permissions when applicable
|
||||
- Clear next steps
|
||||
|
||||
**Information Architecture:**
|
||||
|
||||
- Hierarchical structure with maximum 4 navigation levels
|
||||
- Content ordering: Conceptual → Referential → Procedural → Troubleshooting
|
||||
|
||||
**For detailed structure requirements:** See `./references/style-guide.md` section on Article Structure and Standard Elements.
|
||||
|
||||
### Style Guide Principles
|
||||
|
||||
Apply formatting and style rules from the comprehensive style guide:
|
||||
|
||||
- Language: Clear, simple, active voice, sentence case
|
||||
- Technical formatting: Code in backticks, UI in bold, placeholders in ALL-CAPS
|
||||
- Structure: Numbered lists for procedures, bullets for non-sequential info
|
||||
- Links: Descriptive text, no "click here"
|
||||
- Alerts: Use Note, Tip, Important, Warning, Caution sparingly
|
||||
|
||||
**For detailed formatting rules:** See `./references/style-guide.md` sections on Language and Tone, Technical Writing Conventions, and Structure and Format.
|
||||
|
||||
### Procedural Content Ordering
|
||||
|
||||
Follow standard procedural sequence: Enabling → Using → Managing → Disabling → Destructive
|
||||
|
||||
Within individual steps: Optional info → Reason → Location → Action
|
||||
|
||||
**For complete ordering guidelines:** See `./references/style-guide.md` section on Content Ordering Guidelines.
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### 1. Understand the Audience
|
||||
|
||||
- Identify user expertise level (beginner, intermediate, advanced)
|
||||
- Determine user goals and tasks
|
||||
- Consider context where documentation will be used
|
||||
- Plan appropriate content depth and technical level
|
||||
|
||||
### 2. Choose Content Type
|
||||
|
||||
Select the appropriate content type:
|
||||
|
||||
- **Need to explain a concept?** → Conceptual
|
||||
- **Documenting API or syntax?** → Referential
|
||||
- **How-to for specific task?** → Procedural
|
||||
- **Debugging help?** → Troubleshooting
|
||||
- **Quick setup needed?** → Quickstart (≤5 minutes)
|
||||
- **End-to-end learning?** → Tutorial
|
||||
- **Version changes?** → Release Notes
|
||||
|
||||
### 3. Structure Content
|
||||
|
||||
**Standard content sequence:**
|
||||
|
||||
1. Title (sentence case, descriptive, within character limits)
|
||||
2. Brief intro (1-2 sentences)
|
||||
3. Prerequisites (if applicable)
|
||||
4. Permissions statement (if required)
|
||||
5. Main content (ordered appropriately by type)
|
||||
6. Troubleshooting (embedded when helpful)
|
||||
7. Next steps / Further reading
|
||||
|
||||
### 4. Apply Style Guide
|
||||
|
||||
Follow the comprehensive style guide for:
|
||||
|
||||
- Formatting code, UI elements, and placeholders
|
||||
- Writing clear procedures with proper structure
|
||||
- Adding accessibility features (alt text, sufficient contrast)
|
||||
- Ensuring proper link formatting and context
|
||||
- Using alerts appropriately
|
||||
|
||||
For complete style guide details, see: `./references/style-guide.md`
|
||||
|
||||
### 5. Content Accuracy
|
||||
|
||||
**Critical rule:** Do not invent or assume information not present in source material.
|
||||
|
||||
- If gaps exist, ask user for missing information
|
||||
- Do not create placeholder or speculative content
|
||||
- Verify technical accuracy with authoritative sources
|
||||
- Include working examples when possible
|
||||
|
||||
## Problem-Solving Approach
|
||||
|
||||
### 1. Analysis Phase
|
||||
|
||||
- Review existing documentation structure and patterns
|
||||
- Identify target audience and their needs
|
||||
- Assess information architecture and navigation
|
||||
- Check for consistency with project documentation standards
|
||||
|
||||
### 2. Solution Design
|
||||
|
||||
- Select appropriate content type for the task
|
||||
- Plan information hierarchy and flow
|
||||
- Consider accessibility and localization needs
|
||||
- Design for different user expertise levels
|
||||
|
||||
### 3. Implementation
|
||||
|
||||
- Write clear, concise content following style guide
|
||||
- Structure with appropriate headings and sections
|
||||
- Include concrete examples where helpful
|
||||
- Add tables for complex reference information
|
||||
- Ensure proper formatting of code, UI, and placeholders
|
||||
|
||||
### 4. Validation
|
||||
|
||||
- Verify content accuracy and completeness
|
||||
- Check that examples work as documented
|
||||
- Ensure style guide compliance
|
||||
- Validate accessibility (alt text, structure, contrast)
|
||||
- Confirm navigation and links work correctly
|
||||
|
||||
**Automated validation:** Use `./scripts/validate_markdown.py <file>` to check:
|
||||
- Proper heading hierarchy (no skipped levels)
|
||||
- Code block formatting (language tags, closing backticks)
|
||||
- Link syntax and descriptive link text
|
||||
- Basic document structure
|
||||
|
||||
## Communication Style
|
||||
|
||||
**Be Clear and Actionable:**
|
||||
|
||||
- Use simple, direct language
|
||||
- Provide specific examples and code snippets
|
||||
- Break complex topics into digestible sections
|
||||
- Include visual aids when they clarify concepts
|
||||
|
||||
**Serve Multiple Expertise Levels:**
|
||||
|
||||
- Layer content from simple to complex
|
||||
- Provide quick reference sections
|
||||
- Link to deeper explanations
|
||||
- Use prerequisites to set expectations
|
||||
|
||||
**Focus on User Goals:**
|
||||
|
||||
- Organize by tasks users want to accomplish
|
||||
- Use gerund titles for procedures ("Creating...", "Configuring...")
|
||||
- Include "what you'll learn" or "what you'll build" statements
|
||||
- Provide clear next steps after each article
|
||||
|
||||
## Reference Materials
|
||||
|
||||
This skill references the comprehensive style guide for detailed guidance on all formatting rules.
|
||||
|
||||
**See:** `./references/style-guide.md` for the complete technical writing style guide.
|
||||
|
||||
### Quick Discovery: Search Patterns
|
||||
|
||||
For specific formatting rules in the large style guide, use grep to search:
|
||||
|
||||
- **Alert formatting rules:** Search for `"alert"` in `./references/style-guide.md`
|
||||
- **Code block formatting:** Search for `"code"` or `"backticks"` in `./references/style-guide.md`
|
||||
- **Link formatting:** Search for `"link text"` in `./references/style-guide.md`
|
||||
- **Table formatting:** Search for `"table"` in `./references/style-guide.md`
|
||||
- **Heading hierarchy:** Search for `"heading"` in `./references/style-guide.md`
|
||||
- **Procedural step structure:** Search for `"step structure"` or `"Within Procedural"` in `./references/style-guide.md`
|
||||
- **Alt text requirements:** Search for `"alt text"` in `./references/style-guide.md`
|
||||
- **Placeholder conventions:** Search for `"placeholder"` or `"ALL-CAPS"` in `./references/style-guide.md`
|
||||
|
||||
## Success Criteria
|
||||
|
||||
Documentation is successful when:
|
||||
|
||||
- Content is accessible to the target audience
|
||||
- Structure follows the appropriate content type
|
||||
- Examples clarify complex concepts
|
||||
- Style guide rules are consistently applied
|
||||
- Users can complete tasks using the documentation
|
||||
- Information architecture supports easy navigation
|
||||
- Content is accurate and up-to-date
|
||||
|
||||
## Quick Reference: Common Patterns
|
||||
|
||||
### README Structure
|
||||
|
||||
```markdown
|
||||
# Project Title (sentence case)
|
||||
|
||||
Brief description in 1-2 sentences.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Item 1
|
||||
- Item 2
|
||||
|
||||
## Installation
|
||||
|
||||
1. Step one
|
||||
2. Step two
|
||||
|
||||
## Usage
|
||||
|
||||
Basic usage examples with code blocks.
|
||||
|
||||
## Documentation
|
||||
|
||||
Links to further reading.
|
||||
```
|
||||
|
||||
### API Documentation Pattern
|
||||
|
||||
```markdown
|
||||
## `functionName(param1, param2)`
|
||||
|
||||
Brief description of what the function does.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| --------- | ------ | ----------- |
|
||||
| param1 | string | Description |
|
||||
| param2 | number | Description |
|
||||
|
||||
**Returns:** Description of return value
|
||||
|
||||
**Example:**
|
||||
\`\`\`language
|
||||
// Working code example
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
### Release Notes Pattern
|
||||
|
||||
```markdown
|
||||
# Version X.Y.Z
|
||||
|
||||
## Features
|
||||
|
||||
- New feature description
|
||||
|
||||
## Fixes
|
||||
|
||||
- Bug fix description
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
- Breaking change with migration path
|
||||
|
||||
## Improvements
|
||||
|
||||
- Enhancement description
|
||||
```
|
||||
|
||||
## Remember
|
||||
|
||||
- Always consider the audience first
|
||||
- Choose the right content type for the task
|
||||
- Follow style guide consistently
|
||||
- Do not invent information - ask when unclear
|
||||
- Include working examples
|
||||
- Make content accessible
|
||||
- Structure for easy navigation
|
||||
- Validate before completion
|
||||
609
skills/technical-writer/references/style-guide.md
Normal file
609
skills/technical-writer/references/style-guide.md
Normal file
@@ -0,0 +1,609 @@
|
||||
# Comprehensive Technical Writing Style Guide
|
||||
|
||||
This reference provides detailed guidance for creating professional, accessible, and user-friendly technical documentation.
|
||||
|
||||
## Content Model
|
||||
|
||||
### Content Structure
|
||||
|
||||
- **Hierarchical organization**: Top-level doc sets → Categories → Map topics → Articles
|
||||
- **Category creation threshold**: 10+ articles required for new categories
|
||||
- **Navigation depth**: Maximum 4 levels deep
|
||||
- **Consistent content types**: Each with specific purposes and formats
|
||||
- **Standard elements**: Every article includes titles, intros, permissions, etc.
|
||||
|
||||
## Article Structure and Standard Elements
|
||||
|
||||
### Titles
|
||||
|
||||
**Character limits:**
|
||||
- Categories: 67 character limit
|
||||
- Map topics: 63 character limit
|
||||
- Articles: 80 character limit
|
||||
|
||||
**Formatting:**
|
||||
- Use sentence case (not title case)
|
||||
- Gerund titles for procedural content ("Creating...", "Configuring...")
|
||||
- Avoid "How to" prefix unless required by product convention
|
||||
|
||||
**Examples:**
|
||||
|
||||
✅ Do:
|
||||
- "Set up OAuth for a single-page app"
|
||||
- "Creating a service principal" (procedural/gerund)
|
||||
|
||||
❌ Don't:
|
||||
- "Setting Up OAuth for a Single-Page App" (title case)
|
||||
- "How to set up OAuth" (avoid "How to")
|
||||
|
||||
### Intros
|
||||
|
||||
**Length requirements:**
|
||||
- Articles: 1-2 sentences
|
||||
- Categories/Map topics: 1 sentence
|
||||
|
||||
**Content:**
|
||||
- Must explain what the content covers
|
||||
- Be specific and actionable
|
||||
- Avoid vague language
|
||||
|
||||
**Examples:**
|
||||
|
||||
✅ Do:
|
||||
"This guide shows you how to enable OAuth for single-page apps using PKCE. You'll configure an app, create secrets, and test the flow."
|
||||
|
||||
❌ Don't:
|
||||
"In this document, we will be covering OAuth for single-page applications in depth." (vague, long-winded)
|
||||
|
||||
### Permissions Statements
|
||||
|
||||
**Required for:** All tasks requiring specific permissions
|
||||
|
||||
**Format options:**
|
||||
|
||||
1. **Frontmatter** (preferred):
|
||||
```yaml
|
||||
---
|
||||
required-permissions:
|
||||
role: Owner
|
||||
scope: Subscription
|
||||
---
|
||||
```
|
||||
|
||||
2. **Inline**:
|
||||
"You need the Owner role at the subscription scope to complete these steps."
|
||||
|
||||
**Consistency:** Use the same language patterns across documentation.
|
||||
|
||||
### Required Sections
|
||||
|
||||
When applicable, include these sections:
|
||||
|
||||
**Prerequisites:**
|
||||
- Use structured list format
|
||||
- Be specific about versions, tools, access levels
|
||||
|
||||
Example:
|
||||
- An Azure subscription
|
||||
- The Azure CLI 2.60.0 or later
|
||||
- Owner role at the subscription scope
|
||||
|
||||
**Product callouts:**
|
||||
"This feature is available on the Enterprise plan only."
|
||||
|
||||
**Next steps and Further reading:**
|
||||
- Provide clear next actions
|
||||
- Link to related content
|
||||
- Use descriptive link text
|
||||
|
||||
## Content Types Detailed
|
||||
|
||||
### 1. Conceptual Content
|
||||
|
||||
**Purpose:** Explains what something is and why it's useful
|
||||
|
||||
**Characteristics:**
|
||||
- "About..." article pattern
|
||||
- Defines concepts and terminology
|
||||
- Explains when to use and tradeoffs
|
||||
- Provides context without step-by-step instructions
|
||||
|
||||
**Example:**
|
||||
"About service principals" — defines the concept, when to use it, and tradeoffs.
|
||||
|
||||
### 2. Referential Content
|
||||
|
||||
**Purpose:** Detailed information for active use
|
||||
|
||||
**Characteristics:**
|
||||
- Syntax guides with complete parameter lists
|
||||
- Tables for complex data relationships
|
||||
- Alphabetical or logical organization
|
||||
- Comprehensive but scannable format
|
||||
|
||||
**When to use tables vs. lists:**
|
||||
- **Tables**: Multiple related properties per item
|
||||
- **Lists**: Simple, single-dimension information
|
||||
|
||||
**Structure headers appropriately:**
|
||||
- Long reference content benefits from clear section breaks
|
||||
- Use consistent heading hierarchy
|
||||
- Enable quick scanning and search
|
||||
|
||||
**Example:**
|
||||
"CLI reference for `az ad sp`" — flags, options, examples.
|
||||
|
||||
### 3. Procedural Content
|
||||
|
||||
**Purpose:** Step-by-step task completion
|
||||
|
||||
**Characteristics:**
|
||||
- Numbered lists (sequential steps)
|
||||
- Gerund titles ("Creating...", "Configuring...")
|
||||
- One action per step
|
||||
- Clear prerequisites upfront
|
||||
|
||||
**Step structure:**
|
||||
1. Optional information (if applicable)
|
||||
2. Reason for the step (if not obvious)
|
||||
3. Location where to perform action
|
||||
4. Action to take
|
||||
|
||||
**Example:**
|
||||
"Creating a service principal" — numbered steps start-to-finish.
|
||||
|
||||
### 4. Troubleshooting Content
|
||||
|
||||
**Purpose:** Error resolution and known issues
|
||||
|
||||
**Types:**
|
||||
|
||||
**Known issues** (separate articles):
|
||||
- Complex problems requiring detailed explanation
|
||||
- Multiple potential causes
|
||||
- Ongoing or unresolved issues
|
||||
|
||||
**General troubleshooting** (embedded):
|
||||
- Common errors for specific tasks
|
||||
- Quick fixes and workarounds
|
||||
- Embedded in main task articles
|
||||
|
||||
**Structure:**
|
||||
- Symptom description
|
||||
- Cause explanation
|
||||
- Resolution steps
|
||||
- Prevention guidance
|
||||
|
||||
**Example:**
|
||||
"Fix: AADSTS700016 error" — symptoms, cause, resolution.
|
||||
|
||||
### 5. Quickstart Content
|
||||
|
||||
**Purpose:** Essential steps for quick setup
|
||||
|
||||
**Critical requirements:**
|
||||
- **Time limit**: 5 minutes / 600 words maximum
|
||||
- **Specific intro phrasing**: Must clarify audience and scope
|
||||
- **Audience clarification**: Required for complex products
|
||||
|
||||
**Structure:**
|
||||
1. Before you begin (2-3 prerequisites)
|
||||
2. Create resources (1-2 commands or clicks)
|
||||
3. Run and verify (1 command or screenshot)
|
||||
4. Clean up resources
|
||||
|
||||
**Intro pattern:**
|
||||
"In this quickstart, you [accomplish X]. This guide is for [audience] who want to [goal]."
|
||||
|
||||
**Example:**
|
||||
"Create and deploy your first function app" — 3-5 steps, done in 5 minutes.
|
||||
|
||||
### 6. Tutorial Content
|
||||
|
||||
**Purpose:** Detailed workflow guidance with real-world examples
|
||||
|
||||
**Requirements:**
|
||||
- **Conversational tone**: Required for engagement
|
||||
- **Real examples**: Must use actual, working examples (no placeholder code)
|
||||
- **Conclusion structure**: Specific requirements for wrap-up
|
||||
|
||||
**Characteristics:**
|
||||
- End-to-end scenario
|
||||
- Explains "why" not just "how"
|
||||
- Includes best practices
|
||||
- Shows complete, working solution
|
||||
|
||||
**Conclusion must include:**
|
||||
- Summary of what was accomplished
|
||||
- Link to related concepts
|
||||
- Suggested next steps
|
||||
- Resources for going deeper
|
||||
|
||||
**Example:**
|
||||
"Build a news summarizer with Functions and Cosmos DB" — end-to-end scenario.
|
||||
|
||||
### 7. Release Notes
|
||||
|
||||
**Purpose:** Version-specific changes and updates
|
||||
|
||||
**Requirements:**
|
||||
- **Comprehensive formatting**: Specific categorization rules
|
||||
- **Change categorization**: Features, fixes, improvements, breaking changes, etc.
|
||||
|
||||
**Categories (in order):**
|
||||
1. Breaking Changes (if any)
|
||||
2. Features (new capabilities)
|
||||
3. Improvements (enhancements to existing features)
|
||||
4. Fixes (bug fixes)
|
||||
5. Documentation (doc updates)
|
||||
6. Dependencies (version updates)
|
||||
|
||||
**Format:**
|
||||
```markdown
|
||||
## Version X.Y.Z - YYYY-MM-DD
|
||||
|
||||
### Breaking Changes
|
||||
- Change description with migration path
|
||||
|
||||
### Features
|
||||
- New feature description with brief example
|
||||
|
||||
### Improvements
|
||||
- Enhancement description
|
||||
|
||||
### Fixes
|
||||
- Bug fix description (can reference issue numbers)
|
||||
```
|
||||
|
||||
**Example:**
|
||||
"v1.8.0" — Features, fixes, breaking changes.
|
||||
|
||||
### Combining Content Types
|
||||
|
||||
**Guidelines:**
|
||||
- Longer articles can combine multiple content types
|
||||
- Follow content ordering guidelines
|
||||
- Use clear transitions between sections
|
||||
- Include troubleshooting information frequently
|
||||
|
||||
**Transition examples:**
|
||||
- "Now that you understand the key concepts, follow these steps to enable the feature."
|
||||
- "With the basics covered, let's explore advanced configurations."
|
||||
|
||||
## Content Ordering Guidelines
|
||||
|
||||
### Standard Content Sequence
|
||||
|
||||
1. **Conceptual** - What it is and why it's useful
|
||||
2. **Referential** - Detailed information for active use
|
||||
3. **Procedural** (in this specific order):
|
||||
- **Enabling** - Initial setup/activation
|
||||
- **Using** - Regular operational tasks
|
||||
- **Managing** - Administrative/configuration tasks
|
||||
- **Disabling** - Deactivation procedures
|
||||
- **Destructive** - Deletion/removal tasks
|
||||
4. **Troubleshooting** - Error resolution
|
||||
|
||||
### Within Procedural Steps
|
||||
|
||||
Order information within each step:
|
||||
|
||||
1. **Optional information** (if applicable)
|
||||
- "If you already have X, skip this step."
|
||||
2. **Reason** for the step (if not obvious)
|
||||
- "This keeps latency low."
|
||||
3. **Location** where to perform the action
|
||||
- "In the Azure portal, go to Resource groups..."
|
||||
4. **Action** to take
|
||||
- "...and select Create."
|
||||
|
||||
**Example:**
|
||||
"Create a resource group in the same region as your app. This keeps latency low. In the Azure portal, go to Resource groups and select Create. Name it `my-rg` and select a region."
|
||||
|
||||
## Style Guide Key Points
|
||||
|
||||
### Language and Tone
|
||||
|
||||
**Principles:**
|
||||
- Clear, simple, approachable language
|
||||
- Active voice preferred (passive acceptable when appropriate)
|
||||
- Sentence case for titles and headers
|
||||
- Avoid jargon, idioms, regional phrases
|
||||
- Write for global, multilingual audience
|
||||
|
||||
**Examples:**
|
||||
|
||||
✅ Do:
|
||||
"Run the command and wait for the confirmation message."
|
||||
|
||||
❌ Don't:
|
||||
"One could conceivably run said command prior to proceeding." (jargon, passive, unclear)
|
||||
|
||||
### Technical Writing Conventions
|
||||
|
||||
**Code formatting:**
|
||||
- Use `backticks` for code, file names, commands, parameters
|
||||
- Keep code blocks to ~60 character line length
|
||||
- Avoid command prompts in examples (just show commands)
|
||||
- Use syntax highlighting with proper language tags
|
||||
|
||||
**UI elements:**
|
||||
- Format UI text in **bold** (buttons, menu items, fields)
|
||||
- Use exact text from the interface
|
||||
- Use > for navigation paths: **File > Save As**
|
||||
|
||||
**Placeholders:**
|
||||
- ALL-CAPS with dashes: YOUR-PROJECT, YOUR-RESOURCE-GROUP
|
||||
- Must explain placeholders before or after use
|
||||
- Be consistent with placeholder naming
|
||||
|
||||
**Images:**
|
||||
- Include alt text for all images (40-150 characters)
|
||||
- Alt text describes what's shown, not just "screenshot"
|
||||
- Reference images in text: "as shown in the following image"
|
||||
|
||||
**Examples:**
|
||||
|
||||
✅ Good:
|
||||
- "Select **Create** and run `az group create --name MY-RG --location westus`."
|
||||
- "Replace YOUR-RG with the name of your resource group."
|
||||
- Alt text: "Screenshot of the Azure portal showing the Create resource group form with fields completed"
|
||||
|
||||
### Structure and Format
|
||||
|
||||
**Lists:**
|
||||
|
||||
**Numbered lists** (procedures):
|
||||
- Capitalize first word
|
||||
- Use periods for complete sentences
|
||||
- One action per step
|
||||
- Sequential order matters
|
||||
|
||||
**Bullet lists** (non-sequential):
|
||||
- Use asterisks (*) not dashes
|
||||
- Capitalize first word
|
||||
- Alphabetize when appropriate
|
||||
- Parallel structure
|
||||
|
||||
**Tables:**
|
||||
- Use consistent header formatting
|
||||
- Align content properly (left for text, right for numbers)
|
||||
- Include header row
|
||||
- Keep cells concise
|
||||
|
||||
**Alert Types** (use sparingly):
|
||||
|
||||
- **Note**: Neutral, supplementary information
|
||||
- "The CLI caches credentials for 1 hour."
|
||||
- **Tip**: Helpful shortcuts or best practices
|
||||
- "Use tags to organize resources across subscriptions."
|
||||
- **Important**: Critical information that affects outcomes
|
||||
- "Do not share client secrets. Rotate them every 90 days."
|
||||
- **Warning**: Potential risks or consequences
|
||||
- "Deleting the resource group removes all resources in it."
|
||||
- **Caution**: Actions that could cause data loss or damage
|
||||
- "Export data before disabling the feature to avoid loss."
|
||||
|
||||
### Links and References
|
||||
|
||||
**Internal links:**
|
||||
- Use appropriate formatting for your doc system
|
||||
- Link to specific sections when helpful
|
||||
- Keep link text descriptive
|
||||
|
||||
**Link text:**
|
||||
- Be descriptive (tell what user will find)
|
||||
- Never use "click here" or "read more"
|
||||
- Include context when needed
|
||||
|
||||
**External links:**
|
||||
- Provide full context
|
||||
- Explain why user should follow the link
|
||||
- Consider link rot (prefer stable URLs)
|
||||
|
||||
**Examples:**
|
||||
|
||||
✅ Do:
|
||||
- "See the authentication overview for background on OAuth 2.0."
|
||||
- "For the OAuth 2.1 draft, see the IETF working group page."
|
||||
|
||||
❌ Don't:
|
||||
- "Click here for more info."
|
||||
- "Read more." (no context)
|
||||
|
||||
## Process and Workflow Elements
|
||||
|
||||
### Topics (Metadata)
|
||||
|
||||
**Character limits:**
|
||||
- Keep topics concise
|
||||
- Follow selection criteria for your platform
|
||||
|
||||
**Forbidden patterns:**
|
||||
- Avoid duplicating title text
|
||||
- Don't use as keyword stuffing
|
||||
|
||||
### Tool Switchers
|
||||
|
||||
**When to use:**
|
||||
- Multiple interfaces for same task (Portal, CLI, PowerShell, Terraform)
|
||||
- All methods achieve same outcome
|
||||
- Each deserves equal treatment
|
||||
|
||||
**Format:**
|
||||
- Use tabbed interface when supported
|
||||
- Consistent ordering across docs
|
||||
- Complete examples in each tab
|
||||
|
||||
**Example:**
|
||||
"Portal | CLI | PowerShell | Terraform"
|
||||
|
||||
### Call to Action (CTA)
|
||||
|
||||
**Requirements:**
|
||||
- Consistent formatting
|
||||
- Clear, action-oriented language
|
||||
- Specific next step
|
||||
|
||||
**Examples:**
|
||||
- Next steps: "Next, secure your API keys with Key Vault."
|
||||
- CTA button text: "Save", "Create", "Deploy" (not "Click to save")
|
||||
|
||||
### Reusables and Variables
|
||||
|
||||
**When to use reusables:**
|
||||
- Content repeated verbatim across multiple articles
|
||||
- Maintenance efficiency matters
|
||||
- Content unlikely to need article-specific variations
|
||||
|
||||
**When to inline content:**
|
||||
- Article-specific variations likely
|
||||
- Better readability in source
|
||||
- Single-use content
|
||||
|
||||
**Variable usage:**
|
||||
- Define at document start or first use
|
||||
- Be consistent with variable names
|
||||
- Match placeholder conventions
|
||||
|
||||
**Examples:**
|
||||
- "Set `YOUR-RG`, `YOUR-LOCATION`, and `YOUR-APP-NAME`."
|
||||
- Reusable snippet: Common troubleshooting block for network timeouts
|
||||
|
||||
## Accessibility Requirements
|
||||
|
||||
### Alt Text
|
||||
|
||||
**Requirements:**
|
||||
- 40-150 characters
|
||||
- Describe what's shown, not "screenshot of..."
|
||||
- Include relevant text from image
|
||||
- Convey information, not aesthetics
|
||||
|
||||
**Examples:**
|
||||
✅ "Azure portal showing the Create resource group form with fields completed"
|
||||
❌ "Screenshot" (too vague)
|
||||
|
||||
### Structure
|
||||
|
||||
**Heading hierarchy:**
|
||||
- Use proper heading levels (H1 → H2 → H3)
|
||||
- Don't skip levels
|
||||
- One H1 per page (the title)
|
||||
|
||||
**Reading order:**
|
||||
- Content makes sense when read linearly
|
||||
- Screen reader compatible
|
||||
|
||||
**Color and contrast:**
|
||||
- Don't rely on color alone
|
||||
- Ensure sufficient contrast
|
||||
- Use patterns or labels in addition to color
|
||||
|
||||
### Links
|
||||
|
||||
**Descriptive link text:**
|
||||
- Tells where link goes
|
||||
- Makes sense out of context
|
||||
- Avoid "click here"
|
||||
|
||||
### ARIA (when applicable)
|
||||
|
||||
- Use ARIA labels for complex interactions
|
||||
- Ensure keyboard navigation works
|
||||
- Test with screen readers
|
||||
|
||||
## Localization Considerations
|
||||
|
||||
**Write for translation:**
|
||||
- Avoid idioms and colloquialisms
|
||||
- Use simple sentence structure
|
||||
- Be explicit (avoid implied information)
|
||||
- Watch for cultural references
|
||||
|
||||
**Date and number formatting:**
|
||||
- Use international formats
|
||||
- Provide context for ambiguous formats
|
||||
- Let localization system handle conversion
|
||||
|
||||
**Right-to-left (RTL) languages:**
|
||||
- Ensure UI accommodates RTL
|
||||
- Test with RTL languages
|
||||
- Avoid directional language ("left sidebar")
|
||||
|
||||
**String externalization:**
|
||||
- Use localization keys
|
||||
- Avoid concatenating strings
|
||||
- Plan for text expansion (some languages are longer)
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Use this checklist before publishing:
|
||||
|
||||
**Content:**
|
||||
- [ ] Accurate and technically correct
|
||||
- [ ] Appropriate content type for task
|
||||
- [ ] Complete (no missing steps or information)
|
||||
- [ ] Examples work as documented
|
||||
- [ ] Tone appropriate for audience
|
||||
|
||||
**Structure:**
|
||||
- [ ] Clear title (sentence case, within character limits)
|
||||
- [ ] Brief intro (1-2 sentences)
|
||||
- [ ] Prerequisites listed when needed
|
||||
- [ ] Logical flow and organization
|
||||
- [ ] Clear next steps
|
||||
|
||||
**Style:**
|
||||
- [ ] Sentence case for headers
|
||||
- [ ] Active voice (mostly)
|
||||
- [ ] Code formatted correctly
|
||||
- [ ] Placeholders explained
|
||||
- [ ] Links descriptive and working
|
||||
|
||||
**Accessibility:**
|
||||
- [ ] Alt text for all images
|
||||
- [ ] Proper heading hierarchy
|
||||
- [ ] Sufficient color contrast
|
||||
- [ ] Keyboard accessible
|
||||
|
||||
**Polish:**
|
||||
- [ ] Spell check passed
|
||||
- [ ] Grammar correct
|
||||
- [ ] Consistent terminology
|
||||
- [ ] No jargon or explained when necessary
|
||||
|
||||
## Summary: Quick Decision Tree
|
||||
|
||||
**What type of content do I need?**
|
||||
|
||||
- Explaining a concept? → **Conceptual**
|
||||
- Documenting API/syntax? → **Referential**
|
||||
- How to do a task? → **Procedural**
|
||||
- Fixing errors? → **Troubleshooting**
|
||||
- Quick start (< 5 min)? → **Quickstart**
|
||||
- Learning journey? → **Tutorial**
|
||||
- Version changes? → **Release Notes**
|
||||
|
||||
**How should I structure it?**
|
||||
|
||||
1. Title (sentence case, descriptive)
|
||||
2. Intro (1-2 sentences, specific)
|
||||
3. Prerequisites (if needed)
|
||||
4. Main content (type-appropriate)
|
||||
5. Troubleshooting (when helpful)
|
||||
6. Next steps
|
||||
|
||||
**What voice should I use?**
|
||||
|
||||
- Active, direct, clear
|
||||
- Simple language
|
||||
- Appropriate for global audience
|
||||
- Professional but approachable
|
||||
|
||||
**Did I make it accessible?**
|
||||
|
||||
- Alt text on images
|
||||
- Proper headings
|
||||
- Descriptive links
|
||||
- Sufficient contrast
|
||||
267
skills/technical-writer/scripts/validate_markdown.py
Executable file
267
skills/technical-writer/scripts/validate_markdown.py
Executable file
@@ -0,0 +1,267 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Markdown Documentation Validator
|
||||
|
||||
Validates markdown documentation files for common issues:
|
||||
- Proper heading hierarchy (no skipped levels)
|
||||
- Code block formatting (language tags, closing backticks)
|
||||
- Link syntax validation
|
||||
- Basic structure checks
|
||||
|
||||
Usage:
|
||||
python validate_markdown.py <file_path>
|
||||
python validate_markdown.py <directory_path>
|
||||
"""
|
||||
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from typing import List, Tuple
|
||||
|
||||
|
||||
class ValidationError:
|
||||
"""Represents a validation error with line number and description."""
|
||||
|
||||
def __init__(self, line_num: int, error_type: str, message: str):
|
||||
self.line_num = line_num
|
||||
self.error_type = error_type
|
||||
self.message = message
|
||||
|
||||
def __str__(self):
|
||||
return f"Line {self.line_num}: [{self.error_type}] {self.message}"
|
||||
|
||||
|
||||
class MarkdownValidator:
|
||||
"""Validates markdown documentation files."""
|
||||
|
||||
def __init__(self, file_path: Path):
|
||||
self.file_path = file_path
|
||||
self.errors: List[ValidationError] = []
|
||||
self.lines: List[str] = []
|
||||
self.heading_levels: List[int] = []
|
||||
|
||||
def validate(self) -> List[ValidationError]:
|
||||
"""Run all validation checks and return list of errors."""
|
||||
try:
|
||||
with open(self.file_path, 'r', encoding='utf-8') as f:
|
||||
self.lines = f.readlines()
|
||||
except Exception as e:
|
||||
return [ValidationError(0, "FILE_ERROR", f"Cannot read file: {e}")]
|
||||
|
||||
self._check_heading_hierarchy()
|
||||
self._check_code_blocks()
|
||||
self._check_links()
|
||||
self._check_basic_structure()
|
||||
|
||||
return sorted(self.errors, key=lambda e: e.line_num)
|
||||
|
||||
def _check_heading_hierarchy(self):
|
||||
"""Check that heading levels don't skip (e.g., h1 -> h3)."""
|
||||
prev_level = 0
|
||||
|
||||
for i, line in enumerate(self.lines, 1):
|
||||
# Match ATX-style headings (# Heading)
|
||||
match = re.match(r'^(#{1,6})\s+(.+)', line)
|
||||
if match:
|
||||
level = len(match.group(1))
|
||||
self.heading_levels.append(level)
|
||||
|
||||
# Check for skipped levels
|
||||
if level > prev_level + 1:
|
||||
self.errors.append(ValidationError(
|
||||
i,
|
||||
"HEADING_SKIP",
|
||||
f"Heading level skipped (h{prev_level} -> h{level}). Use h{prev_level + 1} instead."
|
||||
))
|
||||
|
||||
# Check for title case (common mistake)
|
||||
title = match.group(2).strip()
|
||||
if self._is_title_case(title) and level <= 3:
|
||||
self.errors.append(ValidationError(
|
||||
i,
|
||||
"TITLE_CASE",
|
||||
f"Heading appears to use title case. Use sentence case instead: '{title}'"
|
||||
))
|
||||
|
||||
prev_level = level
|
||||
|
||||
def _is_title_case(self, text: str) -> bool:
|
||||
"""Check if text appears to be in title case."""
|
||||
# Skip if too short or starts with code
|
||||
if len(text.split()) < 3 or text.startswith('`'):
|
||||
return False
|
||||
|
||||
words = text.split()
|
||||
# Articles and short words that should be lowercase in sentence case
|
||||
small_words = {'a', 'an', 'the', 'and', 'but', 'or', 'for', 'nor', 'on', 'at', 'to', 'from', 'by', 'with'}
|
||||
|
||||
capitalized_count = sum(1 for word in words[1:] if word and word[0].isupper() and word.lower() not in small_words)
|
||||
|
||||
# If more than 50% of non-first words are capitalized, likely title case
|
||||
return capitalized_count > len(words[1:]) * 0.5
|
||||
|
||||
def _check_code_blocks(self):
|
||||
"""Check code block formatting."""
|
||||
in_code_block = False
|
||||
code_block_start = 0
|
||||
|
||||
for i, line in enumerate(self.lines, 1):
|
||||
# Check for code block fences
|
||||
if line.strip().startswith('```'):
|
||||
if not in_code_block:
|
||||
# Starting a code block
|
||||
in_code_block = True
|
||||
code_block_start = i
|
||||
|
||||
# Check for language tag
|
||||
fence_content = line.strip()[3:].strip()
|
||||
if not fence_content:
|
||||
self.errors.append(ValidationError(
|
||||
i,
|
||||
"CODE_BLOCK_LANG",
|
||||
"Code block missing language identifier (e.g., ```python, ```bash, ```markdown)"
|
||||
))
|
||||
else:
|
||||
# Ending a code block
|
||||
in_code_block = False
|
||||
|
||||
# Check for unclosed code block
|
||||
if in_code_block:
|
||||
self.errors.append(ValidationError(
|
||||
code_block_start,
|
||||
"CODE_BLOCK_UNCLOSED",
|
||||
"Code block opened but never closed"
|
||||
))
|
||||
|
||||
def _check_links(self):
|
||||
"""Check link syntax."""
|
||||
for i, line in enumerate(self.lines, 1):
|
||||
# Find all markdown links [text](url)
|
||||
links = re.finditer(r'\[([^\]]+)\]\(([^)]+)\)', line)
|
||||
|
||||
for match in links:
|
||||
link_text = match.group(1)
|
||||
link_url = match.group(2)
|
||||
|
||||
# Check for "click here" anti-pattern
|
||||
if link_text.lower() in ['click here', 'here', 'read more', 'more']:
|
||||
self.errors.append(ValidationError(
|
||||
i,
|
||||
"LINK_TEXT",
|
||||
f"Non-descriptive link text: '{link_text}'. Use descriptive text that tells where the link goes."
|
||||
))
|
||||
|
||||
# Check for empty link text
|
||||
if not link_text.strip():
|
||||
self.errors.append(ValidationError(
|
||||
i,
|
||||
"LINK_EMPTY",
|
||||
"Link has empty text"
|
||||
))
|
||||
|
||||
# Check for empty URL
|
||||
if not link_url.strip():
|
||||
self.errors.append(ValidationError(
|
||||
i,
|
||||
"LINK_EMPTY_URL",
|
||||
f"Link '{link_text}' has empty URL"
|
||||
))
|
||||
|
||||
def _check_basic_structure(self):
|
||||
"""Check basic document structure."""
|
||||
# Check for at least one H1
|
||||
if not any(line.startswith('# ') for line in self.lines):
|
||||
self.errors.append(ValidationError(
|
||||
1,
|
||||
"NO_H1",
|
||||
"Document should have at least one top-level heading (# Title)"
|
||||
))
|
||||
|
||||
# Check for multiple H1s (often unintended)
|
||||
h1_count = sum(1 for line in self.lines if line.startswith('# '))
|
||||
if h1_count > 1:
|
||||
self.errors.append(ValidationError(
|
||||
1,
|
||||
"MULTIPLE_H1",
|
||||
f"Document has {h1_count} top-level headings. Consider using only one H1 as the document title."
|
||||
))
|
||||
|
||||
|
||||
def validate_file(file_path: Path) -> Tuple[Path, List[ValidationError]]:
|
||||
"""Validate a single markdown file."""
|
||||
validator = MarkdownValidator(file_path)
|
||||
errors = validator.validate()
|
||||
return file_path, errors
|
||||
|
||||
|
||||
def validate_directory(dir_path: Path) -> List[Tuple[Path, List[ValidationError]]]:
|
||||
"""Validate all markdown files in a directory."""
|
||||
results = []
|
||||
|
||||
for md_file in dir_path.rglob('*.md'):
|
||||
file_path, errors = validate_file(md_file)
|
||||
if errors:
|
||||
results.append((file_path, errors))
|
||||
|
||||
return results
|
||||
|
||||
|
||||
def print_results(results: List[Tuple[Path, List[ValidationError]]]):
|
||||
"""Print validation results."""
|
||||
if not results:
|
||||
print("✓ No validation errors found!")
|
||||
return
|
||||
|
||||
total_errors = sum(len(errors) for _, errors in results)
|
||||
|
||||
print(f"\n{'='*70}")
|
||||
print(f"Found {total_errors} validation error(s) in {len(results)} file(s)")
|
||||
print(f"{'='*70}\n")
|
||||
|
||||
for file_path, errors in results:
|
||||
print(f"\n{file_path}:")
|
||||
print("-" * 70)
|
||||
for error in errors:
|
||||
print(f" {error}")
|
||||
|
||||
print(f"\n{'='*70}")
|
||||
print(f"Total: {total_errors} error(s)")
|
||||
print(f"{'='*70}\n")
|
||||
|
||||
|
||||
def main():
|
||||
"""Main entry point."""
|
||||
if len(sys.argv) != 2:
|
||||
print("Usage: python validate_markdown.py <file_or_directory>")
|
||||
sys.exit(1)
|
||||
|
||||
path = Path(sys.argv[1])
|
||||
|
||||
if not path.exists():
|
||||
print(f"Error: Path does not exist: {path}")
|
||||
sys.exit(1)
|
||||
|
||||
results = []
|
||||
|
||||
if path.is_file():
|
||||
if path.suffix == '.md':
|
||||
file_path, errors = validate_file(path)
|
||||
if errors:
|
||||
results.append((file_path, errors))
|
||||
else:
|
||||
print(f"Error: Not a markdown file: {path}")
|
||||
sys.exit(1)
|
||||
elif path.is_dir():
|
||||
results = validate_directory(path)
|
||||
else:
|
||||
print(f"Error: Invalid path: {path}")
|
||||
sys.exit(1)
|
||||
|
||||
print_results(results)
|
||||
|
||||
# Exit with error code if validation errors found
|
||||
sys.exit(1 if results else 0)
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
Reference in New Issue
Block a user