feat(seo): add CITATION.cff and improve AI discoverability
- Add CITATION.cff for academic citations and GitHub citation button - Add "For AI Assistants" section in README with llms.txt reference - Update machine-readable/llms.txt stats (4700+ → 9600+ lines) - Bump version display to 3.8.0 in README footer Improves discoverability in GitHub search, Google Scholar, and AI assistants Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Florian BRUNIAUX
parent
36530c121c
commit
174192f583
11 changed files with 1665 additions and 7 deletions
25
CITATION.cff
Normal file
25
CITATION.cff
Normal file
|
|
@ -0,0 +1,25 @@
|
|||
cff-version: 1.2.0
|
||||
message: "If you use this guide, please cite it as below."
|
||||
type: dataset
|
||||
title: "Claude Code Ultimate Guide"
|
||||
abstract: "Comprehensive community guide for Claude Code (Anthropic's CLI tool). 9,600+ lines of documentation, 87 production-ready templates, 159-question quiz."
|
||||
authors:
|
||||
- family-names: "Bruniaux"
|
||||
given-names: "Florian"
|
||||
affiliation: "Méthode Aristote"
|
||||
version: "3.8.0"
|
||||
date-released: "2026-01-16"
|
||||
license: "CC-BY-SA-4.0"
|
||||
url: "https://github.com/FlorianBruniaux/claude-code-ultimate-guide"
|
||||
repository-code: "https://github.com/FlorianBruniaux/claude-code-ultimate-guide"
|
||||
keywords:
|
||||
- claude-code
|
||||
- anthropic
|
||||
- ai-coding
|
||||
- developer-tools
|
||||
- ai-assistant
|
||||
- prompt-engineering
|
||||
- mcp-servers
|
||||
- productivity
|
||||
- cli-tool
|
||||
- llm
|
||||
27
README.md
27
README.md
|
|
@ -163,15 +163,21 @@ curl -sL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-
|
|||
|
||||
**Want deeper analysis?** Use [`tools/audit-prompt.md`](./tools/audit-prompt.md) for personalized recommendations (~3 min).
|
||||
|
||||
### 🤖 LLM Reference
|
||||
### 🤖 For AI Assistants
|
||||
|
||||
Give any AI assistant instant Claude Code expertise (~2K tokens):
|
||||
This guide is optimized for both human and AI consumption:
|
||||
|
||||
| Resource | Purpose | Tokens |
|
||||
|----------|---------|--------|
|
||||
| **[llms.txt](./machine-readable/llms.txt)** | Standard context file for AI crawlers | ~1K |
|
||||
| **[reference.yaml](./machine-readable/reference.yaml)** | Structured index with line numbers | ~2K |
|
||||
|
||||
**Quick load** (paste in any AI assistant):
|
||||
```bash
|
||||
curl -sL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/machine-readable/reference.yaml
|
||||
```
|
||||
|
||||
**Use cases**: Paste output into ChatGPT/Claude/Gemini, add to system prompts, or reference in Claude Code with `@machine-readable/reference.yaml`
|
||||
**Use cases**: Inject into ChatGPT/Claude/Gemini, add to system prompts, reference in Claude Code with `@machine-readable/reference.yaml`
|
||||
|
||||
**What's inside**: Decision trees, command reference, context zones, MCP servers, agent templates, troubleshooting—optimized for machine consumption. Points to line numbers in the [full guide](./guide/ultimate-guide.md) for deep dives.
|
||||
|
||||
|
|
@ -431,7 +437,8 @@ claude-code-ultimate-guide/
|
|||
│ ├── tdd-with-claude.md
|
||||
│ ├── spec-first.md
|
||||
│ ├── plan-driven.md
|
||||
│ └── iterative-refinement.md
|
||||
│ ├── iterative-refinement.md
|
||||
│ └── pdf-generation.md
|
||||
│
|
||||
├── tools/ # 🔧 Interactive utilities
|
||||
│ ├── audit-prompt.md # Setup audit with recommendations
|
||||
|
|
@ -517,7 +524,7 @@ Copy-paste templates from [`examples/`](./examples/) for immediate use:
|
|||
| [claude-security-review.yml](./examples/github-actions/claude-security-review.yml) | PR open | Security scan (OWASP Top 10) |
|
||||
| [claude-issue-triage.yml](./examples/github-actions/claude-issue-triage.yml) | Issue opened | Auto-triage with labels |
|
||||
|
||||
**[See Complete Catalog](./examples/README.md)** — Includes agents, skills, memory templates, config files, workflows
|
||||
**[See Complete Catalog](./examples/README.md)** | **[Browse Interactive Catalog](./examples/index.html)** — Includes agents, skills, memory templates, config files, workflows
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -652,7 +659,15 @@ If this guide saved you time, helped you master Claude Code, or inspired your wo
|
|||
|
||||
---
|
||||
|
||||
*Version 3.7.1 | January 2026 | Crafted with Claude*
|
||||
## 📬 Stay Updated
|
||||
|
||||
Get notified about major updates, new templates, and Claude Code best practices:
|
||||
|
||||
**[Subscribe to the newsletter](https://buttondown.com/claude-code-guide)** — No spam, 1-2 emails/month max, unsubscribe anytime.
|
||||
|
||||
---
|
||||
|
||||
*Version 3.8.0 | January 2026 | Crafted with Claude*
|
||||
|
||||
<!-- SEO Keywords -->
|
||||
<!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,
|
||||
|
|
|
|||
|
|
@ -2,6 +2,8 @@
|
|||
|
||||
Ready-to-use templates for Claude Code configuration.
|
||||
|
||||
> **[Browse Interactive Catalog](./index.html)** — View, copy, and download all templates with syntax highlighting
|
||||
|
||||
## Structure
|
||||
|
||||
| Folder | Description |
|
||||
|
|
@ -53,6 +55,7 @@ Ready-to-use templates for Claude Code configuration.
|
|||
|------|---------|
|
||||
| [tdd-workflow.md](./skills/tdd-workflow.md) | Test-Driven Development process |
|
||||
| [security-checklist.md](./skills/security-checklist.md) | OWASP Top 10 security checks |
|
||||
| [pdf-generator.md](./skills/pdf-generator.md) | Professional PDF generation (Quarto/Typst) |
|
||||
|
||||
### Commands
|
||||
| File | Trigger | Purpose |
|
||||
|
|
|
|||
764
examples/index.html
Normal file
764
examples/index.html
Normal file
|
|
@ -0,0 +1,764 @@
|
|||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>Claude Code Examples Catalog</title>
|
||||
<meta name="description" content="Browse 50+ ready-to-use templates for Claude Code: agents, commands, hooks, skills, and more.">
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/styles/github-dark.min.css">
|
||||
<style>
|
||||
:root {
|
||||
--bg-primary: #0d1117;
|
||||
--bg-secondary: #161b22;
|
||||
--bg-tertiary: #21262d;
|
||||
--border-default: #30363d;
|
||||
--border-muted: #21262d;
|
||||
--text-primary: #e6edf3;
|
||||
--text-secondary: #8b949e;
|
||||
--text-muted: #6e7681;
|
||||
--accent-green: #238636;
|
||||
--accent-green-hover: #2ea043;
|
||||
--accent-blue: #58a6ff;
|
||||
--accent-purple: #a371f7;
|
||||
--accent-orange: #d29922;
|
||||
--accent-red: #f85149;
|
||||
}
|
||||
|
||||
* {
|
||||
box-sizing: border-box;
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
body {
|
||||
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif;
|
||||
background-color: var(--bg-primary);
|
||||
color: var(--text-primary);
|
||||
line-height: 1.5;
|
||||
min-height: 100vh;
|
||||
}
|
||||
|
||||
.container {
|
||||
max-width: 1200px;
|
||||
margin: 0 auto;
|
||||
padding: 2rem 1rem;
|
||||
}
|
||||
|
||||
header {
|
||||
text-align: center;
|
||||
margin-bottom: 2rem;
|
||||
padding-bottom: 2rem;
|
||||
border-bottom: 1px solid var(--border-default);
|
||||
}
|
||||
|
||||
h1 {
|
||||
font-size: 2rem;
|
||||
font-weight: 600;
|
||||
margin-bottom: 0.5rem;
|
||||
}
|
||||
|
||||
.subtitle {
|
||||
color: var(--text-secondary);
|
||||
font-size: 1.1rem;
|
||||
}
|
||||
|
||||
.search-bar {
|
||||
display: flex;
|
||||
gap: 1rem;
|
||||
margin: 2rem auto;
|
||||
max-width: 600px;
|
||||
}
|
||||
|
||||
.search-input {
|
||||
flex: 1;
|
||||
padding: 0.75rem 1rem;
|
||||
background-color: var(--bg-secondary);
|
||||
border: 1px solid var(--border-default);
|
||||
border-radius: 6px;
|
||||
color: var(--text-primary);
|
||||
font-size: 1rem;
|
||||
}
|
||||
|
||||
.search-input:focus {
|
||||
outline: none;
|
||||
border-color: var(--accent-blue);
|
||||
box-shadow: 0 0 0 3px rgba(88, 166, 255, 0.3);
|
||||
}
|
||||
|
||||
.search-input::placeholder {
|
||||
color: var(--text-muted);
|
||||
}
|
||||
|
||||
.stats {
|
||||
display: flex;
|
||||
gap: 2rem;
|
||||
justify-content: center;
|
||||
margin-bottom: 2rem;
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
|
||||
.stat {
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
.stat-number {
|
||||
font-size: 1.5rem;
|
||||
font-weight: 600;
|
||||
color: var(--accent-blue);
|
||||
}
|
||||
|
||||
.stat-label {
|
||||
color: var(--text-secondary);
|
||||
font-size: 0.875rem;
|
||||
}
|
||||
|
||||
.category {
|
||||
margin-bottom: 1.5rem;
|
||||
background-color: var(--bg-secondary);
|
||||
border: 1px solid var(--border-default);
|
||||
border-radius: 8px;
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
.category-header {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: space-between;
|
||||
padding: 1rem 1.25rem;
|
||||
cursor: pointer;
|
||||
user-select: none;
|
||||
transition: background-color 0.15s;
|
||||
}
|
||||
|
||||
.category-header:hover {
|
||||
background-color: var(--bg-tertiary);
|
||||
}
|
||||
|
||||
.category-title {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.75rem;
|
||||
font-size: 1.1rem;
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.category-icon {
|
||||
font-size: 1.25rem;
|
||||
}
|
||||
|
||||
.category-count {
|
||||
background-color: var(--bg-tertiary);
|
||||
color: var(--text-secondary);
|
||||
padding: 0.125rem 0.5rem;
|
||||
border-radius: 10px;
|
||||
font-size: 0.75rem;
|
||||
font-weight: 500;
|
||||
}
|
||||
|
||||
.category-toggle {
|
||||
color: var(--text-secondary);
|
||||
transition: transform 0.2s;
|
||||
}
|
||||
|
||||
.category.expanded .category-toggle {
|
||||
transform: rotate(180deg);
|
||||
}
|
||||
|
||||
.category-content {
|
||||
display: none;
|
||||
border-top: 1px solid var(--border-default);
|
||||
}
|
||||
|
||||
.category.expanded .category-content {
|
||||
display: block;
|
||||
}
|
||||
|
||||
.category-description {
|
||||
padding: 0.75rem 1.25rem;
|
||||
color: var(--text-secondary);
|
||||
font-size: 0.875rem;
|
||||
background-color: var(--bg-tertiary);
|
||||
}
|
||||
|
||||
.file-list {
|
||||
list-style: none;
|
||||
}
|
||||
|
||||
.file-item {
|
||||
border-bottom: 1px solid var(--border-muted);
|
||||
}
|
||||
|
||||
.file-item:last-child {
|
||||
border-bottom: none;
|
||||
}
|
||||
|
||||
.file-header {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: space-between;
|
||||
padding: 0.75rem 1.25rem;
|
||||
gap: 1rem;
|
||||
}
|
||||
|
||||
.file-info {
|
||||
flex: 1;
|
||||
min-width: 0;
|
||||
}
|
||||
|
||||
.file-name {
|
||||
font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace;
|
||||
font-size: 0.875rem;
|
||||
color: var(--accent-blue);
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
.file-name:hover {
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
.file-description {
|
||||
font-size: 0.8125rem;
|
||||
color: var(--text-secondary);
|
||||
margin-top: 0.25rem;
|
||||
white-space: nowrap;
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
}
|
||||
|
||||
.file-actions {
|
||||
display: flex;
|
||||
gap: 0.5rem;
|
||||
flex-shrink: 0;
|
||||
}
|
||||
|
||||
.btn {
|
||||
padding: 0.375rem 0.75rem;
|
||||
border-radius: 6px;
|
||||
font-size: 0.75rem;
|
||||
font-weight: 500;
|
||||
cursor: pointer;
|
||||
transition: all 0.15s;
|
||||
border: 1px solid var(--border-default);
|
||||
background-color: var(--bg-tertiary);
|
||||
color: var(--text-primary);
|
||||
}
|
||||
|
||||
.btn:hover {
|
||||
background-color: var(--border-default);
|
||||
}
|
||||
|
||||
.btn-view {
|
||||
background-color: transparent;
|
||||
}
|
||||
|
||||
.btn-view.active {
|
||||
background-color: var(--accent-blue);
|
||||
border-color: var(--accent-blue);
|
||||
color: white;
|
||||
}
|
||||
|
||||
.btn-copy {
|
||||
background-color: var(--accent-green);
|
||||
border-color: var(--accent-green);
|
||||
color: white;
|
||||
}
|
||||
|
||||
.btn-copy:hover {
|
||||
background-color: var(--accent-green-hover);
|
||||
}
|
||||
|
||||
.btn-copy.copied {
|
||||
background-color: var(--accent-purple);
|
||||
border-color: var(--accent-purple);
|
||||
}
|
||||
|
||||
.btn-download {
|
||||
background-color: transparent;
|
||||
color: var(--text-secondary);
|
||||
}
|
||||
|
||||
.file-content {
|
||||
display: none;
|
||||
padding: 0;
|
||||
background-color: var(--bg-primary);
|
||||
border-top: 1px solid var(--border-muted);
|
||||
}
|
||||
|
||||
.file-item.viewing .file-content {
|
||||
display: block;
|
||||
}
|
||||
|
||||
.file-content pre {
|
||||
margin: 0;
|
||||
padding: 1rem 1.25rem;
|
||||
overflow-x: auto;
|
||||
font-size: 0.8125rem;
|
||||
line-height: 1.6;
|
||||
}
|
||||
|
||||
.file-content code {
|
||||
font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, monospace;
|
||||
}
|
||||
|
||||
.toast {
|
||||
position: fixed;
|
||||
bottom: 2rem;
|
||||
left: 50%;
|
||||
transform: translateX(-50%) translateY(100px);
|
||||
background-color: var(--accent-green);
|
||||
color: white;
|
||||
padding: 0.75rem 1.5rem;
|
||||
border-radius: 8px;
|
||||
font-weight: 500;
|
||||
opacity: 0;
|
||||
transition: all 0.3s;
|
||||
z-index: 1000;
|
||||
}
|
||||
|
||||
.toast.show {
|
||||
transform: translateX(-50%) translateY(0);
|
||||
opacity: 1;
|
||||
}
|
||||
|
||||
.no-results {
|
||||
text-align: center;
|
||||
padding: 3rem;
|
||||
color: var(--text-secondary);
|
||||
}
|
||||
|
||||
.no-results-icon {
|
||||
font-size: 3rem;
|
||||
margin-bottom: 1rem;
|
||||
}
|
||||
|
||||
footer {
|
||||
text-align: center;
|
||||
margin-top: 3rem;
|
||||
padding-top: 2rem;
|
||||
border-top: 1px solid var(--border-default);
|
||||
color: var(--text-secondary);
|
||||
font-size: 0.875rem;
|
||||
}
|
||||
|
||||
footer a {
|
||||
color: var(--accent-blue);
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
footer a:hover {
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
@media (max-width: 640px) {
|
||||
.container {
|
||||
padding: 1rem 0.75rem;
|
||||
}
|
||||
|
||||
h1 {
|
||||
font-size: 1.5rem;
|
||||
}
|
||||
|
||||
.stats {
|
||||
gap: 1rem;
|
||||
}
|
||||
|
||||
.file-header {
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
|
||||
.file-actions {
|
||||
width: 100%;
|
||||
justify-content: flex-end;
|
||||
margin-top: 0.5rem;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<header>
|
||||
<h1>Claude Code Examples</h1>
|
||||
<p class="subtitle">Ready-to-use templates for agents, commands, hooks, and more</p>
|
||||
</header>
|
||||
|
||||
<div class="search-bar">
|
||||
<input type="text" class="search-input" id="searchInput" placeholder="Search examples..." autocomplete="off">
|
||||
</div>
|
||||
|
||||
<div class="stats" id="stats"></div>
|
||||
|
||||
<main id="catalog"></main>
|
||||
|
||||
<div id="noResults" class="no-results" style="display: none;">
|
||||
<div class="no-results-icon">🔍</div>
|
||||
<p>No examples found matching your search.</p>
|
||||
</div>
|
||||
|
||||
<footer>
|
||||
<p>
|
||||
Part of the <a href="https://github.com/anthropics/claude-code-guide">Claude Code Ultimate Guide</a>
|
||||
• <a href="../guide/ultimate-guide.md">Read the Guide</a>
|
||||
• <a href="./README.md">View on GitHub</a>
|
||||
</p>
|
||||
</footer>
|
||||
</div>
|
||||
|
||||
<div class="toast" id="toast">Copied to clipboard!</div>
|
||||
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/highlight.min.js"></script>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/powershell.min.js"></script>
|
||||
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.9.0/languages/yaml.min.js"></script>
|
||||
<script>
|
||||
// Examples data structure
|
||||
const EXAMPLES = {
|
||||
agents: {
|
||||
icon: "🤖",
|
||||
description: "Custom AI personas for specialized tasks. Place in .claude/agents/ or ~/.claude/agents/",
|
||||
files: [
|
||||
{ name: "code-reviewer.md", path: "agents/code-reviewer.md", description: "Thorough code review with best practices" },
|
||||
{ name: "test-writer.md", path: "agents/test-writer.md", description: "TDD/BDD test generation specialist" },
|
||||
{ name: "security-auditor.md", path: "agents/security-auditor.md", description: "Security vulnerability detection (OWASP)" },
|
||||
{ name: "refactoring-specialist.md", path: "agents/refactoring-specialist.md", description: "Clean code refactoring expert" },
|
||||
{ name: "output-evaluator.md", path: "agents/output-evaluator.md", description: "LLM-as-a-Judge quality gate" }
|
||||
]
|
||||
},
|
||||
skills: {
|
||||
icon: "📚",
|
||||
description: "Reusable knowledge modules. Place in .claude/skills/ or ~/.claude/skills/",
|
||||
files: [
|
||||
{ name: "tdd-workflow.md", path: "skills/tdd-workflow.md", description: "Test-Driven Development process" },
|
||||
{ name: "security-checklist.md", path: "skills/security-checklist.md", description: "OWASP Top 10 security checks" }
|
||||
]
|
||||
},
|
||||
commands: {
|
||||
icon: "⚡",
|
||||
description: "Custom slash commands. Place in .claude/commands/ or ~/.claude/commands/",
|
||||
files: [
|
||||
{ name: "commit.md", path: "commands/commit.md", description: "/commit - Conventional commit messages" },
|
||||
{ name: "pr.md", path: "commands/pr.md", description: "/pr - Create well-structured PRs" },
|
||||
{ name: "review-pr.md", path: "commands/review-pr.md", description: "/review-pr - PR review workflow" },
|
||||
{ name: "release-notes.md", path: "commands/release-notes.md", description: "/release-notes - Generate in 3 formats" },
|
||||
{ name: "sonarqube.md", path: "commands/sonarqube.md", description: "/sonarqube - Analyze SonarCloud issues" },
|
||||
{ name: "generate-tests.md", path: "commands/generate-tests.md", description: "/generate-tests - Test generation" },
|
||||
{ name: "git-worktree.md", path: "commands/git-worktree.md", description: "/git-worktree - Isolated worktree setup" },
|
||||
{ name: "diagnose.md", path: "commands/diagnose.md", description: "/diagnose - Interactive troubleshooting" },
|
||||
{ name: "validate-changes.md", path: "commands/validate-changes.md", description: "/validate-changes - Pre-commit validation" }
|
||||
]
|
||||
},
|
||||
"hooks/bash": {
|
||||
icon: "🔒",
|
||||
description: "Event-driven automation scripts (Bash). Place in .claude/hooks/ or ~/.claude/hooks/",
|
||||
files: [
|
||||
{ name: "dangerous-actions-blocker.sh", path: "hooks/bash/dangerous-actions-blocker.sh", description: "Block dangerous commands/edits" },
|
||||
{ name: "security-check.sh", path: "hooks/bash/security-check.sh", description: "Block secrets in commands" },
|
||||
{ name: "prompt-injection-detector.sh", path: "hooks/bash/prompt-injection-detector.sh", description: "Detect injection attempts" },
|
||||
{ name: "unicode-injection-scanner.sh", path: "hooks/bash/unicode-injection-scanner.sh", description: "Detect zero-width, RTL, ANSI escape" },
|
||||
{ name: "repo-integrity-scanner.sh", path: "hooks/bash/repo-integrity-scanner.sh", description: "Scan README/package.json for injection" },
|
||||
{ name: "mcp-config-integrity.sh", path: "hooks/bash/mcp-config-integrity.sh", description: "Verify MCP config hash (CVE)" },
|
||||
{ name: "output-secrets-scanner.sh", path: "hooks/bash/output-secrets-scanner.sh", description: "Detect secrets in output" },
|
||||
{ name: "auto-format.sh", path: "hooks/bash/auto-format.sh", description: "Auto-format after edits" },
|
||||
{ name: "notification.sh", path: "hooks/bash/notification.sh", description: "macOS sound alerts" },
|
||||
{ name: "output-validator.sh", path: "hooks/bash/output-validator.sh", description: "Heuristic output validation" },
|
||||
{ name: "session-logger.sh", path: "hooks/bash/session-logger.sh", description: "Log operations for monitoring" },
|
||||
{ name: "pre-commit-evaluator.sh", path: "hooks/bash/pre-commit-evaluator.sh", description: "LLM-as-a-Judge pre-commit" },
|
||||
{ name: "privacy-warning.sh", path: "hooks/bash/privacy-warning.sh", description: "Warn on privacy-sensitive ops" },
|
||||
{ name: "claudemd-scanner.sh", path: "hooks/bash/claudemd-scanner.sh", description: "Scan CLAUDE.md for issues" }
|
||||
]
|
||||
},
|
||||
"hooks/powershell": {
|
||||
icon: "🪟",
|
||||
description: "Event-driven automation scripts (PowerShell/Windows)",
|
||||
files: [
|
||||
{ name: "security-check.ps1", path: "hooks/powershell/security-check.ps1", description: "Block secrets in commands" },
|
||||
{ name: "auto-format.ps1", path: "hooks/powershell/auto-format.ps1", description: "Auto-format after edits" }
|
||||
]
|
||||
},
|
||||
config: {
|
||||
icon: "⚙️",
|
||||
description: "Configuration file templates. Place in .claude/ or ~/.claude/",
|
||||
files: [
|
||||
{ name: "settings.json", path: "config/settings.json", description: "Hooks and preferences config" },
|
||||
{ name: "mcp.json", path: "config/mcp.json", description: "MCP servers configuration" },
|
||||
{ name: ".gitignore-claude", path: "config/.gitignore-claude", description: "Git ignore patterns for Claude files" }
|
||||
]
|
||||
},
|
||||
memory: {
|
||||
icon: "🧠",
|
||||
description: "CLAUDE.md memory file templates for persistent context",
|
||||
files: [
|
||||
{ name: "CLAUDE.md.project-template", path: "memory/CLAUDE.md.project-template", description: "Team project memory template" },
|
||||
{ name: "CLAUDE.md.personal-template", path: "memory/CLAUDE.md.personal-template", description: "Personal global memory template" }
|
||||
]
|
||||
},
|
||||
scripts: {
|
||||
icon: "🛠️",
|
||||
description: "Utility scripts for setup, diagnostics, and monitoring",
|
||||
files: [
|
||||
{ name: "audit-scan.sh", path: "scripts/audit-scan.sh", description: "Fast setup audit scanner" },
|
||||
{ name: "check-claude.sh", path: "scripts/check-claude.sh", description: "Health check (macOS/Linux)" },
|
||||
{ name: "check-claude.ps1", path: "scripts/check-claude.ps1", description: "Health check (Windows)" },
|
||||
{ name: "clean-reinstall-claude.sh", path: "scripts/clean-reinstall-claude.sh", description: "Clean reinstall (macOS/Linux)" },
|
||||
{ name: "clean-reinstall-claude.ps1", path: "scripts/clean-reinstall-claude.ps1", description: "Clean reinstall (Windows)" },
|
||||
{ name: "session-stats.sh", path: "scripts/session-stats.sh", description: "Analyze session logs & costs" },
|
||||
{ name: "session-search.sh", path: "scripts/session-search.sh", description: "Search & resume sessions" }
|
||||
]
|
||||
},
|
||||
"github-actions": {
|
||||
icon: "🚀",
|
||||
description: "CI/CD workflows for GitHub Actions automation",
|
||||
files: [
|
||||
{ name: "claude-pr-auto-review.yml", path: "github-actions/claude-pr-auto-review.yml", description: "Auto code review on PRs" },
|
||||
{ name: "claude-security-review.yml", path: "github-actions/claude-security-review.yml", description: "Security-focused PR scan" },
|
||||
{ name: "claude-issue-triage.yml", path: "github-actions/claude-issue-triage.yml", description: "Auto-triage issues with labels" }
|
||||
]
|
||||
},
|
||||
workflows: {
|
||||
icon: "📋",
|
||||
description: "Advanced development workflow guides",
|
||||
files: [
|
||||
{ name: "database-branch-setup.md", path: "workflows/database-branch-setup.md", description: "Isolated feature dev with DB branches" }
|
||||
]
|
||||
},
|
||||
modes: {
|
||||
icon: "🎭",
|
||||
description: "Behavioral modes for Claude (SuperClaude framework). Place in ~/.claude/",
|
||||
files: [
|
||||
{ name: "MODE_Learning.md", path: "modes/MODE_Learning.md", description: "Just-in-time explanations mode" }
|
||||
]
|
||||
}
|
||||
};
|
||||
|
||||
// State
|
||||
let contentCache = {};
|
||||
let expandedCategories = new Set();
|
||||
|
||||
// DOM elements
|
||||
const catalogEl = document.getElementById('catalog');
|
||||
const statsEl = document.getElementById('stats');
|
||||
const searchInput = document.getElementById('searchInput');
|
||||
const noResultsEl = document.getElementById('noResults');
|
||||
const toastEl = document.getElementById('toast');
|
||||
|
||||
// Utility functions
|
||||
function getLanguage(filename) {
|
||||
const ext = filename.split('.').pop().toLowerCase();
|
||||
const langMap = {
|
||||
'md': 'markdown',
|
||||
'json': 'json',
|
||||
'yml': 'yaml',
|
||||
'yaml': 'yaml',
|
||||
'sh': 'bash',
|
||||
'ps1': 'powershell',
|
||||
'gitignore': 'plaintext'
|
||||
};
|
||||
return langMap[ext] || 'plaintext';
|
||||
}
|
||||
|
||||
function showToast(message) {
|
||||
toastEl.textContent = message;
|
||||
toastEl.classList.add('show');
|
||||
setTimeout(() => toastEl.classList.remove('show'), 2000);
|
||||
}
|
||||
|
||||
async function loadContent(path) {
|
||||
if (contentCache[path]) {
|
||||
return contentCache[path];
|
||||
}
|
||||
try {
|
||||
const response = await fetch(path);
|
||||
if (!response.ok) throw new Error('Failed to load');
|
||||
const text = await response.text();
|
||||
contentCache[path] = text;
|
||||
return text;
|
||||
} catch (error) {
|
||||
return `Error loading file: ${error.message}`;
|
||||
}
|
||||
}
|
||||
|
||||
async function copyToClipboard(path) {
|
||||
const content = await loadContent(path);
|
||||
try {
|
||||
await navigator.clipboard.writeText(content);
|
||||
showToast('Copied to clipboard!');
|
||||
return true;
|
||||
} catch (error) {
|
||||
showToast('Failed to copy');
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
function downloadFile(path, filename) {
|
||||
const a = document.createElement('a');
|
||||
a.href = path;
|
||||
a.download = filename;
|
||||
document.body.appendChild(a);
|
||||
a.click();
|
||||
document.body.removeChild(a);
|
||||
}
|
||||
|
||||
async function toggleView(path, contentEl, viewBtn) {
|
||||
const fileItem = contentEl.closest('.file-item');
|
||||
const isViewing = fileItem.classList.contains('viewing');
|
||||
|
||||
if (isViewing) {
|
||||
fileItem.classList.remove('viewing');
|
||||
viewBtn.classList.remove('active');
|
||||
viewBtn.textContent = 'View';
|
||||
} else {
|
||||
// Load and display content
|
||||
const content = await loadContent(path);
|
||||
const filename = path.split('/').pop();
|
||||
const language = getLanguage(filename);
|
||||
|
||||
contentEl.innerHTML = `<pre><code class="language-${language}">${escapeHtml(content)}</code></pre>`;
|
||||
hljs.highlightElement(contentEl.querySelector('code'));
|
||||
|
||||
fileItem.classList.add('viewing');
|
||||
viewBtn.classList.add('active');
|
||||
viewBtn.textContent = 'Hide';
|
||||
}
|
||||
}
|
||||
|
||||
function escapeHtml(text) {
|
||||
const div = document.createElement('div');
|
||||
div.textContent = text;
|
||||
return div.innerHTML;
|
||||
}
|
||||
|
||||
function renderStats() {
|
||||
let totalFiles = 0;
|
||||
let totalCategories = Object.keys(EXAMPLES).length;
|
||||
|
||||
Object.values(EXAMPLES).forEach(cat => {
|
||||
totalFiles += cat.files.length;
|
||||
});
|
||||
|
||||
statsEl.innerHTML = `
|
||||
<div class="stat">
|
||||
<div class="stat-number">${totalFiles}</div>
|
||||
<div class="stat-label">Templates</div>
|
||||
</div>
|
||||
<div class="stat">
|
||||
<div class="stat-number">${totalCategories}</div>
|
||||
<div class="stat-label">Categories</div>
|
||||
</div>
|
||||
<div class="stat">
|
||||
<div class="stat-number">100%</div>
|
||||
<div class="stat-label">Copy-Ready</div>
|
||||
</div>
|
||||
`;
|
||||
}
|
||||
|
||||
function renderCatalog(filter = '') {
|
||||
const filterLower = filter.toLowerCase();
|
||||
let html = '';
|
||||
let hasResults = false;
|
||||
|
||||
Object.entries(EXAMPLES).forEach(([categoryId, category]) => {
|
||||
const filteredFiles = category.files.filter(file =>
|
||||
file.name.toLowerCase().includes(filterLower) ||
|
||||
file.description.toLowerCase().includes(filterLower) ||
|
||||
categoryId.toLowerCase().includes(filterLower)
|
||||
);
|
||||
|
||||
if (filteredFiles.length === 0) return;
|
||||
hasResults = true;
|
||||
|
||||
const isExpanded = expandedCategories.has(categoryId) || filter !== '';
|
||||
const categoryName = categoryId.replace('/', ' / ').replace(/(^|\s)\S/g, t => t.toUpperCase());
|
||||
|
||||
html += `
|
||||
<div class="category ${isExpanded ? 'expanded' : ''}" data-category="${categoryId}">
|
||||
<div class="category-header" onclick="toggleCategory('${categoryId}')">
|
||||
<div class="category-title">
|
||||
<span class="category-icon">${category.icon}</span>
|
||||
<span>${categoryName}</span>
|
||||
<span class="category-count">${filteredFiles.length}</span>
|
||||
</div>
|
||||
<span class="category-toggle">▼</span>
|
||||
</div>
|
||||
<div class="category-content">
|
||||
<div class="category-description">${category.description}</div>
|
||||
<ul class="file-list">
|
||||
${filteredFiles.map(file => `
|
||||
<li class="file-item" data-path="${file.path}">
|
||||
<div class="file-header">
|
||||
<div class="file-info">
|
||||
<a class="file-name" href="${file.path}" target="_blank">${file.name}</a>
|
||||
<div class="file-description">${file.description}</div>
|
||||
</div>
|
||||
<div class="file-actions">
|
||||
<button class="btn btn-view" onclick="handleView('${file.path}', this)">View</button>
|
||||
<button class="btn btn-copy" onclick="handleCopy('${file.path}', this)">Copy</button>
|
||||
<button class="btn btn-download" onclick="downloadFile('${file.path}', '${file.name}')">↓</button>
|
||||
</div>
|
||||
</div>
|
||||
<div class="file-content"></div>
|
||||
</li>
|
||||
`).join('')}
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
`;
|
||||
});
|
||||
|
||||
catalogEl.innerHTML = html;
|
||||
noResultsEl.style.display = hasResults ? 'none' : 'block';
|
||||
}
|
||||
|
||||
function toggleCategory(categoryId) {
|
||||
if (expandedCategories.has(categoryId)) {
|
||||
expandedCategories.delete(categoryId);
|
||||
} else {
|
||||
expandedCategories.add(categoryId);
|
||||
}
|
||||
renderCatalog(searchInput.value);
|
||||
}
|
||||
|
||||
async function handleView(path, btn) {
|
||||
const fileItem = btn.closest('.file-item');
|
||||
const contentEl = fileItem.querySelector('.file-content');
|
||||
await toggleView(path, contentEl, btn);
|
||||
}
|
||||
|
||||
async function handleCopy(path, btn) {
|
||||
const success = await copyToClipboard(path);
|
||||
if (success) {
|
||||
const originalText = btn.textContent;
|
||||
btn.textContent = '✓';
|
||||
btn.classList.add('copied');
|
||||
setTimeout(() => {
|
||||
btn.textContent = originalText;
|
||||
btn.classList.remove('copied');
|
||||
}, 1500);
|
||||
}
|
||||
}
|
||||
|
||||
// Event listeners
|
||||
let debounceTimer;
|
||||
searchInput.addEventListener('input', (e) => {
|
||||
clearTimeout(debounceTimer);
|
||||
debounceTimer = setTimeout(() => {
|
||||
renderCatalog(e.target.value);
|
||||
}, 150);
|
||||
});
|
||||
|
||||
// Keyboard shortcuts
|
||||
document.addEventListener('keydown', (e) => {
|
||||
if (e.key === '/' && document.activeElement !== searchInput) {
|
||||
e.preventDefault();
|
||||
searchInput.focus();
|
||||
}
|
||||
if (e.key === 'Escape') {
|
||||
searchInput.blur();
|
||||
searchInput.value = '';
|
||||
renderCatalog('');
|
||||
}
|
||||
});
|
||||
|
||||
// Initialize
|
||||
renderStats();
|
||||
renderCatalog();
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
368
examples/skills/pdf-generator.md
Normal file
368
examples/skills/pdf-generator.md
Normal file
|
|
@ -0,0 +1,368 @@
|
|||
---
|
||||
name: pdf-generator
|
||||
description: Generate professional PDFs using Quarto/Typst stack with modern design template
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
# PDF Generator Skill
|
||||
|
||||
Generate professional PDFs with modern typography using Quarto + Typst.
|
||||
|
||||
## Skill Purpose
|
||||
|
||||
This skill assists with:
|
||||
- Setting up Quarto/Typst projects
|
||||
- Creating document templates
|
||||
- Generating PDFs from Markdown
|
||||
- Troubleshooting rendering issues
|
||||
- Customizing design systems
|
||||
|
||||
## Stack
|
||||
|
||||
| Tool | Version | Role |
|
||||
|------|---------|------|
|
||||
| **Quarto** | ≥1.4.0 | Document rendering engine |
|
||||
| **Typst** | 0.13.0 | Modern typography (integrated) |
|
||||
| **Pandoc** | 3.x | Markdown conversion (integrated) |
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install quarto
|
||||
|
||||
# Linux
|
||||
wget https://github.com/quarto-dev/quarto-cli/releases/download/v1.4.555/quarto-1.4.555-linux-amd64.deb
|
||||
sudo dpkg -i quarto-1.4.555-linux-amd64.deb
|
||||
|
||||
# Windows
|
||||
winget install Posit.Quarto
|
||||
```
|
||||
|
||||
### Generate PDF
|
||||
|
||||
```bash
|
||||
# Single file
|
||||
quarto render document.qmd
|
||||
|
||||
# All files
|
||||
quarto render *.qmd
|
||||
|
||||
# Preview with hot-reload
|
||||
quarto preview document.qmd
|
||||
```
|
||||
|
||||
## YAML Frontmatter Template
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Document Title"
|
||||
subtitle: "Optional subtitle"
|
||||
author: "Author Name"
|
||||
date: 2026-01-17
|
||||
date-format: "MMMM YYYY"
|
||||
format:
|
||||
typst:
|
||||
toc: true
|
||||
toc-depth: 2
|
||||
section-numbering: "1.1"
|
||||
lang: en
|
||||
---
|
||||
```
|
||||
|
||||
### Available Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `title` | string | Main title (cover page) |
|
||||
| `subtitle` | string | Optional subtitle |
|
||||
| `author` | string | Author(s) |
|
||||
| `date` | date | ISO format (YYYY-MM-DD) |
|
||||
| `date-format` | string | Display format (`MMMM YYYY`) |
|
||||
| `toc` | boolean | Show table of contents |
|
||||
| `toc-depth` | number | TOC depth (1-3) |
|
||||
| `section-numbering` | string | Format (`1.1`, `1.a`) |
|
||||
| `lang` | string | Language (`fr`, `en`) |
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
project/
|
||||
├── _extensions/
|
||||
│ └── custom-template/
|
||||
│ ├── _extension.yml # Extension metadata
|
||||
│ ├── typst-template.typ # Main template
|
||||
│ └── typst-show.typ # Quarto → Typst bridge
|
||||
├── document.qmd # Source file
|
||||
└── document.pdf # Generated output
|
||||
```
|
||||
|
||||
## Markdown Syntax
|
||||
|
||||
### Page Breaks
|
||||
|
||||
```markdown
|
||||
{{< pagebreak >}}
|
||||
```
|
||||
|
||||
### Code Blocks
|
||||
|
||||
Standard fenced blocks with syntax highlighting:
|
||||
|
||||
````markdown
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
````
|
||||
|
||||
### Tables
|
||||
|
||||
```markdown
|
||||
| Column A | Column B |
|
||||
|----------|----------|
|
||||
| Value 1 | Value 2 |
|
||||
```
|
||||
|
||||
### Images
|
||||
|
||||
```markdown
|
||||
{width=50%}
|
||||
```
|
||||
|
||||
## Custom Template
|
||||
|
||||
### Extension Configuration
|
||||
|
||||
Create `_extensions/mytemplate/_extension.yml`:
|
||||
|
||||
```yaml
|
||||
title: My Template
|
||||
author: Your Name
|
||||
version: 1.0.0
|
||||
contributes:
|
||||
formats:
|
||||
typst:
|
||||
template: typst-template.typ
|
||||
template-partials:
|
||||
- typst-show.typ
|
||||
```
|
||||
|
||||
### Design System (Typst)
|
||||
|
||||
```typst
|
||||
// Colors (Slate + Indigo palette)
|
||||
#let primary = rgb("#0f172a") // Slate 900 - titles
|
||||
#let secondary = rgb("#334155") // Slate 700 - subtitles
|
||||
#let accent = rgb("#6366f1") // Indigo 500 - accents
|
||||
#let muted = rgb("#64748b") // Slate 500 - metadata
|
||||
#let light-bg = rgb("#f8fafc") // Slate 50 - code bg
|
||||
#let border-light = rgb("#e2e8f0") // Slate 200 - borders
|
||||
```
|
||||
|
||||
### Typography
|
||||
|
||||
```typst
|
||||
#set text(
|
||||
font: ("Inter", "Helvetica Neue", "Arial"),
|
||||
size: 11pt,
|
||||
)
|
||||
|
||||
#set par(
|
||||
leading: 0.75em,
|
||||
justify: true,
|
||||
)
|
||||
|
||||
// Code blocks
|
||||
#show raw.where(block: true): it => {
|
||||
block(
|
||||
fill: light-bg,
|
||||
stroke: (left: 3pt + accent),
|
||||
inset: 10pt,
|
||||
radius: 4pt,
|
||||
it,
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Callout Boxes
|
||||
|
||||
```typst
|
||||
#let info(title: "Note", body) = {
|
||||
block(
|
||||
fill: rgb("#E0F2FE"),
|
||||
stroke: (left: 3pt + rgb("#0284C7")),
|
||||
inset: 12pt,
|
||||
[*#title*: #body]
|
||||
)
|
||||
}
|
||||
|
||||
#let warning(title: "Warning", body) = {
|
||||
block(
|
||||
fill: rgb("#FEF3C7"),
|
||||
stroke: (left: 3pt + rgb("#D97706")),
|
||||
inset: 12pt,
|
||||
[*#title*: #body]
|
||||
)
|
||||
}
|
||||
|
||||
#let success(title: "Success", body) = {
|
||||
block(
|
||||
fill: rgb("#DCFCE7"),
|
||||
stroke: (left: 3pt + rgb("#16A34A")),
|
||||
inset: 12pt,
|
||||
[*#title*: #body]
|
||||
)
|
||||
}
|
||||
|
||||
#let danger(title: "Danger", body) = {
|
||||
block(
|
||||
fill: rgb("#FEE2E2"),
|
||||
stroke: (left: 3pt + rgb("#DC2626")),
|
||||
inset: 12pt,
|
||||
[*#title*: #body]
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Quick Validation
|
||||
|
||||
```bash
|
||||
# Check Quarto version
|
||||
quarto --version # >= 1.4.0
|
||||
|
||||
# Verify extension exists
|
||||
ls _extensions/*/
|
||||
|
||||
# Validate code block pairs (must be even)
|
||||
grep -c '^```' document.qmd
|
||||
|
||||
# Check encoding
|
||||
file -i document.qmd # Must show utf-8
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
|
||||
| Issue | Cause | Fix |
|
||||
|-------|-------|-----|
|
||||
| Nested code blocks break | Inner ` ``` ` closes outer | Use 4+ backticks for outer |
|
||||
| Tables render as code | Unmatched ` ``` ` above | Check delimiter count |
|
||||
| Extension not found | Wrong directory | Verify `_extensions/` path |
|
||||
| Font warnings | Fonts not installed | Normal; uses fallbacks |
|
||||
| Characters broken | Wrong encoding | Convert to UTF-8 |
|
||||
|
||||
### Nested Code Blocks
|
||||
|
||||
Use more backticks for outer block:
|
||||
|
||||
`````markdown
|
||||
````markdown
|
||||
# This is the outer block
|
||||
|
||||
```bash
|
||||
echo "This is nested"
|
||||
```
|
||||
|
||||
Outer continues...
|
||||
````
|
||||
`````
|
||||
|
||||
### Validation Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
for f in *.qmd; do
|
||||
count=$(grep -c '^```' "$f")
|
||||
if [ $((count % 2)) -ne 0 ]; then
|
||||
echo "ERROR: $f has odd count ($count)"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
### Full Validation Pipeline
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# validate-qmd.sh
|
||||
|
||||
echo "=== Validating QMD files ==="
|
||||
errors=0
|
||||
|
||||
for f in *.qmd; do
|
||||
# Check code block pairs
|
||||
count=$(grep -c '^```' "$f")
|
||||
if [ $((count % 2)) -ne 0 ]; then
|
||||
echo "ERROR: $f - odd code block count ($count)"
|
||||
((errors++))
|
||||
fi
|
||||
|
||||
# Check UTF-8
|
||||
encoding=$(file -i "$f" | grep -o 'charset=[^;]*')
|
||||
if [[ "$encoding" != *"utf-8"* ]]; then
|
||||
echo "WARNING: $f - encoding is $encoding"
|
||||
fi
|
||||
done
|
||||
|
||||
echo "=== Validation complete: $errors errors ==="
|
||||
exit $errors
|
||||
```
|
||||
|
||||
## Example Use Cases
|
||||
|
||||
### Technical Documentation
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "API Reference"
|
||||
subtitle: "v2.0"
|
||||
author: "Engineering Team"
|
||||
date: 2026-01-17
|
||||
format:
|
||||
typst:
|
||||
toc: true
|
||||
toc-depth: 3
|
||||
---
|
||||
|
||||
# Authentication
|
||||
|
||||
All requests require an API key...
|
||||
```
|
||||
|
||||
### Whitepaper Series
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Security Best Practices"
|
||||
series: "Engineering Whitepapers"
|
||||
wp-number: "03"
|
||||
author: "Security Team"
|
||||
date: 2026-01-17
|
||||
format:
|
||||
whitepaper-typst:
|
||||
toc: true
|
||||
---
|
||||
```
|
||||
|
||||
### Internal Report
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Q1 Performance Report"
|
||||
author: "Analytics Team"
|
||||
date: 2026-01-17
|
||||
date-format: "Q1 YYYY"
|
||||
format:
|
||||
typst:
|
||||
toc: false
|
||||
---
|
||||
```
|
||||
|
||||
## Resources
|
||||
|
||||
- [Quarto Documentation](https://quarto.org/docs/guide/)
|
||||
- [Typst Documentation](https://typst.app/docs/)
|
||||
- [Quarto + Typst Guide](https://quarto.org/docs/output-formats/typst.html)
|
||||
- [Workflow Guide](../../guide/workflows/pdf-generation.md)
|
||||
|
|
@ -51,6 +51,8 @@ Organized in a 6-tier pyramid from strategic orchestration down to optimization
|
|||
- **When to use**: Complex enterprise projects needing governance
|
||||
- **When to avoid**: Small teams, MVPs, rapid prototyping
|
||||
|
||||
> **Emerging**: [Ralph Inferno](https://github.com/sandstream/ralph-inferno) implements autonomous multi-persona workflows (Analyst→PM→UX→Architect→Business) with VM-based execution and self-correcting E2E loops. Experimental but interesting for "vibe coding at scale".
|
||||
|
||||
---
|
||||
|
||||
### Tier 2: Specification & Architecture
|
||||
|
|
|
|||
451
guide/workflows/pdf-generation.md
Normal file
451
guide/workflows/pdf-generation.md
Normal file
|
|
@ -0,0 +1,451 @@
|
|||
# PDF Generation with Claude Code
|
||||
|
||||
> **Confidence**: Tier 2 — Based on production-tested workflow with Quarto/Typst stack.
|
||||
|
||||
Generate professional PDFs (documentation, whitepapers, reports) using Claude Code with modern typography and design.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [TL;DR](#tldr)
|
||||
2. [When to Use](#when-to-use)
|
||||
3. [Stack Overview](#stack-overview)
|
||||
4. [Setup](#setup)
|
||||
5. [Workflow](#workflow)
|
||||
6. [Integration with Claude Code](#integration-with-claude-code)
|
||||
7. [Customization](#customization)
|
||||
8. [Troubleshooting](#troubleshooting)
|
||||
9. [See Also](#see-also)
|
||||
|
||||
---
|
||||
|
||||
## TL;DR
|
||||
|
||||
```bash
|
||||
# Install
|
||||
brew install quarto # macOS
|
||||
|
||||
# Generate
|
||||
quarto render document.qmd # → document.pdf
|
||||
|
||||
# Preview
|
||||
quarto preview document.qmd # Hot-reload
|
||||
```
|
||||
|
||||
**Stack**: Quarto (orchestration) + Typst (typography) + Pandoc (markdown)
|
||||
|
||||
---
|
||||
|
||||
## When to Use
|
||||
|
||||
| Use Case | Good Fit | Alternative |
|
||||
|----------|----------|-------------|
|
||||
| Technical documentation | ✅ | — |
|
||||
| Whitepapers / Reports | ✅ | — |
|
||||
| API documentation | ⚠️ | OpenAPI + Redoc |
|
||||
| Slides / Presentations | ⚠️ | Quarto Revealjs |
|
||||
| Quick notes | ❌ | Plain Markdown |
|
||||
| Collaborative editing | ❌ | Google Docs, Notion |
|
||||
|
||||
**Best for**: Long-form technical content requiring professional layout, version control, and reproducibility.
|
||||
|
||||
---
|
||||
|
||||
## Stack Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ Your .qmd File │
|
||||
│ (Markdown + YAML frontmatter) │
|
||||
└─────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ Quarto │
|
||||
│ (Document rendering engine) │
|
||||
│ • Processes YAML metadata │
|
||||
│ • Handles extensions │
|
||||
│ • Manages output formats │
|
||||
└─────────────────────────────────────────────────┘
|
||||
│
|
||||
┌─────────────┴─────────────┐
|
||||
▼ ▼
|
||||
┌─────────────────────┐ ┌─────────────────────┐
|
||||
│ Pandoc │ │ Typst │
|
||||
│ (MD → AST → ?) │ │ (Typography/PDF) │
|
||||
│ • Markdown parser │ │ • Modern engine │
|
||||
│ • AST transforms │ │ • Fast compilation │
|
||||
│ • Format bridges │ │ • No LaTeX needed │
|
||||
└─────────────────────┘ └─────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────┐
|
||||
│ document.pdf │
|
||||
│ (Professional typography output) │
|
||||
└─────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
| Component | Version | Role |
|
||||
|-----------|---------|------|
|
||||
| **Quarto** | ≥1.4.0 | Orchestration, extensions, multi-format |
|
||||
| **Typst** | 0.13.0 | Modern typography (replaces LaTeX) |
|
||||
| **Pandoc** | 3.x | Markdown parsing (bundled with Quarto) |
|
||||
|
||||
---
|
||||
|
||||
## Setup
|
||||
|
||||
### Installation
|
||||
|
||||
**macOS**:
|
||||
```bash
|
||||
brew install quarto
|
||||
```
|
||||
|
||||
**Linux (Debian/Ubuntu)**:
|
||||
```bash
|
||||
wget https://github.com/quarto-dev/quarto-cli/releases/download/v1.4.555/quarto-1.4.555-linux-amd64.deb
|
||||
sudo dpkg -i quarto-1.4.555-linux-amd64.deb
|
||||
```
|
||||
|
||||
**Windows**:
|
||||
```powershell
|
||||
winget install Posit.Quarto
|
||||
```
|
||||
|
||||
**Verify**:
|
||||
```bash
|
||||
quarto --version # Should be ≥1.4.0
|
||||
```
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
project/
|
||||
├── _extensions/ # Quarto extensions (templates)
|
||||
│ └── custom-template/
|
||||
│ ├── _extension.yml
|
||||
│ ├── typst-template.typ
|
||||
│ └── typst-show.typ
|
||||
├── documents/
|
||||
│ ├── guide.qmd # Source file
|
||||
│ └── guide.pdf # Generated output
|
||||
└── assets/
|
||||
└── logo.png # Shared assets
|
||||
```
|
||||
|
||||
### Minimal Document
|
||||
|
||||
Create `document.qmd`:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "My Document"
|
||||
author: "Author Name"
|
||||
date: 2026-01-17
|
||||
format:
|
||||
typst:
|
||||
toc: true
|
||||
lang: en
|
||||
---
|
||||
|
||||
# Introduction
|
||||
|
||||
Your content here...
|
||||
|
||||
## Section 1
|
||||
|
||||
More content with **bold** and `code`.
|
||||
|
||||
```bash
|
||||
echo "Code blocks work!"
|
||||
```
|
||||
|
||||
## Section 2
|
||||
|
||||
| Column A | Column B |
|
||||
|----------|----------|
|
||||
| Data 1 | Data 2 |
|
||||
```
|
||||
|
||||
Generate:
|
||||
```bash
|
||||
quarto render document.qmd # Creates document.pdf
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Content-First Approach
|
||||
|
||||
```
|
||||
1. Write content in Markdown (.qmd)
|
||||
2. Add YAML frontmatter for metadata
|
||||
3. Preview with hot-reload
|
||||
4. Generate final PDF
|
||||
5. Version control both source and PDF
|
||||
```
|
||||
|
||||
### 2. Available YAML Parameters
|
||||
|
||||
| Parameter | Type | Description | Example |
|
||||
|-----------|------|-------------|---------|
|
||||
| `title` | string | Main title | `"Technical Guide"` |
|
||||
| `subtitle` | string | Secondary title | `"v2.0 Edition"` |
|
||||
| `author` | string/array | Author(s) | `"John Doe"` |
|
||||
| `date` | date | Document date | `2026-01-17` |
|
||||
| `date-format` | string | Display format | `"MMMM YYYY"` |
|
||||
| `toc` | boolean | Table of contents | `true` |
|
||||
| `toc-depth` | number | TOC levels (1-3) | `2` |
|
||||
| `lang` | string | Language | `fr` or `en` |
|
||||
| `section-numbering` | string | Number format | `"1.1"` |
|
||||
|
||||
### 3. Markdown Features
|
||||
|
||||
**Page Breaks**:
|
||||
```markdown
|
||||
{{< pagebreak >}}
|
||||
```
|
||||
|
||||
**Code Blocks** (with syntax highlighting):
|
||||
````markdown
|
||||
```typescript
|
||||
function hello(): string {
|
||||
return "world";
|
||||
}
|
||||
```
|
||||
````
|
||||
|
||||
**Tables**:
|
||||
```markdown
|
||||
| Feature | Supported |
|
||||
|---------|-----------|
|
||||
| Tables | ✅ |
|
||||
| Images | ✅ |
|
||||
| Links | ✅ |
|
||||
```
|
||||
|
||||
**Images**:
|
||||
```markdown
|
||||
{width=50%}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Claude Code
|
||||
|
||||
### Using the pdf-generator Skill
|
||||
|
||||
Invoke the skill for guided PDF generation:
|
||||
|
||||
```
|
||||
/pdf-generator
|
||||
```
|
||||
|
||||
The skill provides:
|
||||
- Template with YAML frontmatter
|
||||
- Design system configuration
|
||||
- Common troubleshooting fixes
|
||||
- Generation commands
|
||||
|
||||
### Prompt Examples
|
||||
|
||||
**Generate documentation**:
|
||||
```
|
||||
Create a technical guide for our API as a Quarto document.
|
||||
Use the Typst format with a table of contents.
|
||||
Include sections for: Authentication, Endpoints, Error Codes.
|
||||
```
|
||||
|
||||
**Convert existing Markdown**:
|
||||
```
|
||||
Convert README.md to a professional PDF.
|
||||
Add a cover page with title and date.
|
||||
Use Quarto/Typst format.
|
||||
```
|
||||
|
||||
**Create template**:
|
||||
```
|
||||
Create a Quarto extension for our company's document style:
|
||||
- Logo in header
|
||||
- Custom colors: primary #0f172a, accent #6366f1
|
||||
- Inter font for body, JetBrains Mono for code
|
||||
```
|
||||
|
||||
### With Plan Mode
|
||||
|
||||
For complex documents:
|
||||
```
|
||||
/plan
|
||||
|
||||
I need to create a series of 5 technical whitepapers.
|
||||
Plan the structure:
|
||||
1. Common template/extension
|
||||
2. Shared assets
|
||||
3. Build automation
|
||||
4. Version management
|
||||
```
|
||||
|
||||
### With Hooks
|
||||
|
||||
Auto-generate PDF on save:
|
||||
|
||||
```yaml
|
||||
# .claude/hooks.yaml
|
||||
post_edit:
|
||||
- pattern: "**/*.qmd"
|
||||
command: "quarto render $FILE"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Customization
|
||||
|
||||
### Custom Template Extension
|
||||
|
||||
Create `_extensions/mytemplate/_extension.yml`:
|
||||
|
||||
```yaml
|
||||
title: My Template
|
||||
author: Your Name
|
||||
version: 1.0.0
|
||||
contributes:
|
||||
formats:
|
||||
typst:
|
||||
template: typst-template.typ
|
||||
template-partials:
|
||||
- typst-show.typ
|
||||
```
|
||||
|
||||
### Typst Template Variables
|
||||
|
||||
In `typst-template.typ`:
|
||||
|
||||
```typst
|
||||
// Colors
|
||||
#let primary = rgb("#0f172a") // Dark text
|
||||
#let secondary = rgb("#334155") // Lighter text
|
||||
#let accent = rgb("#6366f1") // Highlights
|
||||
|
||||
// Typography
|
||||
#set text(
|
||||
font: ("Inter", "Helvetica Neue", "Arial"),
|
||||
size: 11pt,
|
||||
)
|
||||
|
||||
#set par(
|
||||
leading: 0.75em, // Line height
|
||||
justify: true,
|
||||
)
|
||||
|
||||
// Code blocks
|
||||
#show raw.where(block: true): it => {
|
||||
block(
|
||||
fill: rgb("#f8fafc"),
|
||||
stroke: (left: 3pt + accent),
|
||||
inset: 10pt,
|
||||
radius: 4pt,
|
||||
it,
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Callout Boxes
|
||||
|
||||
Define in template:
|
||||
|
||||
```typst
|
||||
#let info(title: "Note", body) = {
|
||||
block(
|
||||
fill: rgb("#E0F2FE"),
|
||||
stroke: (left: 3pt + rgb("#0284C7")),
|
||||
inset: 12pt,
|
||||
radius: 4pt,
|
||||
[*#title*: #body]
|
||||
)
|
||||
}
|
||||
|
||||
#let warning(title: "Warning", body) = { ... }
|
||||
#let success(title: "Success", body) = { ... }
|
||||
#let danger(title: "Danger", body) = { ... }
|
||||
```
|
||||
|
||||
Use in document:
|
||||
```typst
|
||||
#info[This is an informational note.]
|
||||
#warning(title: "Attention")[Check your configuration.]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Quick Checks
|
||||
|
||||
```bash
|
||||
# Verify Quarto
|
||||
quarto --version
|
||||
|
||||
# Check extension exists
|
||||
ls _extensions/*/
|
||||
|
||||
# Validate code block pairs (must be even)
|
||||
grep -c '^```' document.qmd
|
||||
|
||||
# Check encoding
|
||||
file -i document.qmd # Should show utf-8
|
||||
```
|
||||
|
||||
### Common Issues
|
||||
|
||||
| Issue | Symptom | Fix |
|
||||
|-------|---------|-----|
|
||||
| Nested code blocks | Content escapes block | Use 4+ backticks for outer block |
|
||||
| Tables as code | Grey background | Check unmatched ` ``` ` above |
|
||||
| Missing extension | "Extension not found" | Verify `_extensions/` path |
|
||||
| Font warnings | "unknown font family" | Normal; uses fallbacks |
|
||||
| Special chars broken | `?` or garbled | Convert to UTF-8 |
|
||||
|
||||
### Nested Code Blocks
|
||||
|
||||
**Problem**: Inner code block closes outer block prematurely.
|
||||
|
||||
**Solution**: Use more backticks for outer block:
|
||||
|
||||
`````markdown
|
||||
````markdown
|
||||
# Outer block with 4 backticks
|
||||
|
||||
```bash
|
||||
echo "Inner block with 3 backticks"
|
||||
```
|
||||
|
||||
Outer block continues...
|
||||
````
|
||||
`````
|
||||
|
||||
### Validation Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# validate-qmd.sh
|
||||
|
||||
for f in *.qmd; do
|
||||
count=$(grep -c '^```' "$f")
|
||||
if [ $((count % 2)) -ne 0 ]; then
|
||||
echo "ERROR: $f has odd code block count ($count)"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Quarto Documentation](https://quarto.org/docs/guide/)
|
||||
- [Typst Documentation](https://typst.app/docs/)
|
||||
- [Quarto + Typst Guide](https://quarto.org/docs/output-formats/typst.html)
|
||||
- [examples/skills/pdf-generator.md](../../examples/skills/pdf-generator.md) — Skill template
|
||||
- [whitepapers/README.md](../../whitepapers/README.md) — Production example
|
||||
|
|
@ -6,7 +6,7 @@
|
|||
|
||||
This repository provides everything needed to go from Claude Code beginner to power user:
|
||||
|
||||
1. **Complete Guide** (`guide/ultimate-guide.md`) - 4700+ lines covering all aspects of Claude Code
|
||||
1. **Complete Guide** (`guide/ultimate-guide.md`) - 9,600+ lines covering all aspects of Claude Code
|
||||
2. **Cheatsheet** (`guide/cheatsheet.md`) - 1-page printable daily reference
|
||||
3. **Architecture Internals** (`guide/architecture.md`) - How Claude Code works under the hood (master loop, tools, context)
|
||||
4. **Audit Prompt** (`tools/audit-prompt.md`) - Self-contained prompt to analyze your Claude Code setup against best practices
|
||||
|
|
|
|||
|
|
@ -15,6 +15,10 @@ deep_dive:
|
|||
# Session management
|
||||
session_search: "guide/observability.md:29"
|
||||
session_search_script: "examples/scripts/session-search.sh"
|
||||
# PDF Generation
|
||||
pdf_generation: "guide/workflows/pdf-generation.md"
|
||||
pdf_generator_skill: "examples/skills/pdf-generator.md"
|
||||
whitepapers_example: "whitepapers/README.md"
|
||||
# Architecture internals (guide/architecture.md)
|
||||
architecture_master_loop: "guide/architecture.md:60"
|
||||
architecture_tools: "guide/architecture.md:130"
|
||||
|
|
|
|||
23
quiz/package-lock.json
generated
23
quiz/package-lock.json
generated
|
|
@ -16,6 +16,9 @@
|
|||
"bin": {
|
||||
"claude-quiz": "src/index.js"
|
||||
},
|
||||
"devDependencies": {
|
||||
"js-yaml": "^4.1.1"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=18.0.0"
|
||||
}
|
||||
|
|
@ -89,6 +92,13 @@
|
|||
"url": "https://github.com/chalk/ansi-styles?sponsor=1"
|
||||
}
|
||||
},
|
||||
"node_modules/argparse": {
|
||||
"version": "2.0.1",
|
||||
"resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
|
||||
"integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
|
||||
"dev": true,
|
||||
"license": "Python-2.0"
|
||||
},
|
||||
"node_modules/base64-js": {
|
||||
"version": "1.5.1",
|
||||
"resolved": "https://registry.npmjs.org/base64-js/-/base64-js-1.5.1.tgz",
|
||||
|
|
@ -344,6 +354,19 @@
|
|||
"url": "https://github.com/sponsors/sindresorhus"
|
||||
}
|
||||
},
|
||||
"node_modules/js-yaml": {
|
||||
"version": "4.1.1",
|
||||
"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz",
|
||||
"integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"argparse": "^2.0.1"
|
||||
},
|
||||
"bin": {
|
||||
"js-yaml": "bin/js-yaml.js"
|
||||
}
|
||||
},
|
||||
"node_modules/log-symbols": {
|
||||
"version": "4.1.0",
|
||||
"resolved": "https://registry.npmjs.org/log-symbols/-/log-symbols-4.1.0.tgz",
|
||||
|
|
|
|||
|
|
@ -27,5 +27,8 @@
|
|||
},
|
||||
"engines": {
|
||||
"node": ">=18.0.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"js-yaml": "^4.1.1"
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue