@knowcode/doc-builder 1.4.9 → 1.4.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude/settings.local.json +22 -0
- package/CHANGELOG.md +27 -9
- package/README.md +2 -0
- package/assets/css/notion-style.css +5 -9
- package/html/README.html +139 -5
- package/html/claude-workflow-guide.html +450 -0
- package/html/css/notion-style.css +5 -9
- package/html/vercel.json +29 -0
- package/knowcode-doc-builder-1.4.4.tgz +0 -0
- package/lib/core-builder.js +19 -5
- package/package/CACHE-BUSTING-GUIDE.md +82 -0
- package/package/CHANGELOG.md +902 -0
- package/package/README.md +248 -0
- package/package/assets/css/notion-style.css +1914 -0
- package/package/assets/js/auth.js +67 -0
- package/package/assets/js/main.js +1331 -0
- package/package/cli.js +764 -0
- package/package/index.js +38 -0
- package/package/knowcode-doc-builder-1.3.15.tgz +0 -0
- package/package/lib/builder.js +32 -0
- package/package/lib/config.js +278 -0
- package/package/lib/core-builder.js +957 -0
- package/package/lib/deploy.js +497 -0
- package/package/lib/dev-server.js +96 -0
- package/package/package.json +34 -0
- package/package/scripts/npx-runner.js +27 -0
- package/package/scripts/setup.js +56 -0
- package/package/test-cache-bust.sh +43 -0
- package/package.json +1 -1
- package/knowcode-doc-builder-1.4.8.tgz +0 -0
|
@@ -0,0 +1,450 @@
|
|
|
1
|
+
<!DOCTYPE html>
|
|
2
|
+
<html lang="en">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="UTF-8">
|
|
5
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
6
|
+
<meta name="description" content="Documentation site built with @knowcode/doc-builder">
|
|
7
|
+
<title>Claude + CLAUDE.md Documentation Workflow Guide - Documentation</title>
|
|
8
|
+
|
|
9
|
+
<!-- Fonts -->
|
|
10
|
+
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
|
|
11
|
+
|
|
12
|
+
<!-- Icons -->
|
|
13
|
+
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css">
|
|
14
|
+
|
|
15
|
+
<!-- Mermaid -->
|
|
16
|
+
<script src="https://cdn.jsdelivr.net/npm/mermaid@10.6.1/dist/mermaid.min.js"></script>
|
|
17
|
+
|
|
18
|
+
<!-- Styles -->
|
|
19
|
+
<link rel="stylesheet" href="/css/notion-style.css">
|
|
20
|
+
|
|
21
|
+
<!-- Favicon -->
|
|
22
|
+
<link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>📚</text></svg>">
|
|
23
|
+
</head>
|
|
24
|
+
<body>
|
|
25
|
+
<!-- Header -->
|
|
26
|
+
<header class="header">
|
|
27
|
+
<div class="header-content">
|
|
28
|
+
<a href="/index.html" class="logo">Documentation</a>
|
|
29
|
+
|
|
30
|
+
<div class="header-actions">
|
|
31
|
+
<div class="deployment-info">
|
|
32
|
+
<span class="deployment-date" title="Built with doc-builder v1.4.10">Last updated: Jul 21, 2025, 12:11 PM UTC</span>
|
|
33
|
+
</div>
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
<button id="theme-toggle" class="theme-toggle" aria-label="Toggle theme">
|
|
38
|
+
<i class="fas fa-moon"></i>
|
|
39
|
+
</button>
|
|
40
|
+
|
|
41
|
+
<button id="menu-toggle" class="menu-toggle" aria-label="Toggle menu">
|
|
42
|
+
<i class="fas fa-bars"></i>
|
|
43
|
+
</button>
|
|
44
|
+
</div>
|
|
45
|
+
</div>
|
|
46
|
+
</header>
|
|
47
|
+
|
|
48
|
+
<!-- Preview Banner -->
|
|
49
|
+
<div id="preview-banner" class="preview-banner">
|
|
50
|
+
<div class="banner-content">
|
|
51
|
+
<i class="fas fa-exclamation-triangle banner-icon"></i>
|
|
52
|
+
<span class="banner-text">This documentation is a preview version - some content may be incomplete</span>
|
|
53
|
+
<button id="dismiss-banner" class="banner-dismiss" aria-label="Dismiss banner">
|
|
54
|
+
<i class="fas fa-times"></i>
|
|
55
|
+
</button>
|
|
56
|
+
</div>
|
|
57
|
+
</div>
|
|
58
|
+
|
|
59
|
+
<!-- Breadcrumbs -->
|
|
60
|
+
<nav class="breadcrumbs" id="breadcrumbs">
|
|
61
|
+
<!-- Breadcrumbs will be generated by JavaScript -->
|
|
62
|
+
</nav>
|
|
63
|
+
|
|
64
|
+
<!-- Main Content -->
|
|
65
|
+
<div class="main-wrapper">
|
|
66
|
+
<!-- Sidebar -->
|
|
67
|
+
<aside class="sidebar">
|
|
68
|
+
<div class="sidebar-header">
|
|
69
|
+
<div class="filter-box">
|
|
70
|
+
<input type="text" placeholder="Filter items..." class="filter-input" id="nav-filter">
|
|
71
|
+
<i class="fas fa-search filter-icon"></i>
|
|
72
|
+
</div>
|
|
73
|
+
</div>
|
|
74
|
+
<nav class="navigation">
|
|
75
|
+
|
|
76
|
+
<div class="nav-section" data-level="0">
|
|
77
|
+
<a class="nav-title expanded" href="/README.html" >
|
|
78
|
+
<i class="fas fa-home"></i> Documentation
|
|
79
|
+
</a>
|
|
80
|
+
<div class="nav-content" >
|
|
81
|
+
<a href="/README.html" class="nav-item" data-tooltip="> Transform your markdown documentation into beautiful, searchable websites with Notion-inspired styling Create stunning documentation sites in minute..."><i class="fas fa-file-alt"></i> Overview</a>
|
|
82
|
+
<a href="/claude-workflow-guide.html" class="nav-item active" data-tooltip="**Generated**: 2025-07-21 10:00 UTC **Status**: Complete **Verified**: ✅ This guide demonstrates an efficient workflow for using Claude Code with a re..."><i class="fas fa-file-alt"></i> Claude Workflow Guide</a></div></div>
|
|
83
|
+
</nav>
|
|
84
|
+
<div class="resize-handle"></div>
|
|
85
|
+
</aside>
|
|
86
|
+
|
|
87
|
+
<!-- Content Area -->
|
|
88
|
+
<main class="content">
|
|
89
|
+
<div class="content-inner">
|
|
90
|
+
<h1>Claude + CLAUDE.md Documentation Workflow Guide</h1>
|
|
91
|
+
<p><strong>Generated</strong>: 2025-07-21 10:00 UTC<br><strong>Status</strong>: Complete<br><strong>Verified</strong>: ✅</p>
|
|
92
|
+
<h2>Overview</h2>
|
|
93
|
+
<p>This guide demonstrates an efficient workflow for using Claude Code with a refined CLAUDE.md file to create high-quality documentation and deploy it to Vercel using the @knowcode/doc-builder tool.</p>
|
|
94
|
+
<h2>Workflow Overview</h2>
|
|
95
|
+
<div class="mermaid-wrapper">
|
|
96
|
+
<div class="mermaid-title">Diagram</div>
|
|
97
|
+
<div class="mermaid">graph TD
|
|
98
|
+
A[Start Project] --> B[Setup CLAUDE.md]
|
|
99
|
+
B --> C[Configure doc-builder]
|
|
100
|
+
C --> D[Create Documentation with Claude]
|
|
101
|
+
D --> E[Build Static Site]
|
|
102
|
+
E --> F[Deploy to Vercel]
|
|
103
|
+
F --> G[Live Documentation]
|
|
104
|
+
|
|
105
|
+
B -.-> H[Refine Instructions]
|
|
106
|
+
H -.-> D
|
|
107
|
+
|
|
108
|
+
D --> I{Review Quality}
|
|
109
|
+
I -->|Needs Improvement| H
|
|
110
|
+
I -->|Good| E
|
|
111
|
+
|
|
112
|
+
style A fill:#e1f5fe
|
|
113
|
+
style G fill:#c8e6c9
|
|
114
|
+
style H fill:#fff3e0</div>
|
|
115
|
+
</div>
|
|
116
|
+
<h2>Step 1: Setting Up CLAUDE.md</h2>
|
|
117
|
+
<h3>1.1 Project-Level CLAUDE.md</h3>
|
|
118
|
+
<p>Create a <code>CLAUDE.md</code> file in your project root with specific instructions for documentation:</p>
|
|
119
|
+
<pre><code class="language-markdown"># CLAUDE.md - [Your Project Name]
|
|
120
|
+
|
|
121
|
+
## Documentation Standards
|
|
122
|
+
|
|
123
|
+
### Document Structure
|
|
124
|
+
- All documentation goes in the `/docs` directory
|
|
125
|
+
- Use hierarchical folder structure for organization
|
|
126
|
+
- Follow naming convention: `{component}-{topic}-guide.md`
|
|
127
|
+
|
|
128
|
+
### Content Requirements
|
|
129
|
+
- Include mermaid diagrams for complex workflows
|
|
130
|
+
- Mark verified (✅) vs speculated (❓) information
|
|
131
|
+
- Add timestamps to all documents
|
|
132
|
+
- Include practical examples
|
|
133
|
+
|
|
134
|
+
### Writing Style
|
|
135
|
+
- Use clear, concise language
|
|
136
|
+
- Target intermediate technical audience
|
|
137
|
+
- Include code examples with syntax highlighting
|
|
138
|
+
- Add troubleshooting sections
|
|
139
|
+
|
|
140
|
+
### Metadata Format
|
|
141
|
+
</code></pre>
|
|
142
|
+
<p><strong>Generated</strong>: YYYY-MM-DD HH:MM UTC<br><strong>Status</strong>: Draft/Complete<br><strong>Verified</strong>: ✅/❓</p>
|
|
143
|
+
<pre><code>
|
|
144
|
+
</code></pre>
|
|
145
|
+
<h3>1.2 Global CLAUDE.md Best Practices</h3>
|
|
146
|
+
<p>Your global <code>~/.claude/CLAUDE.md</code> should include:</p>
|
|
147
|
+
<div class="mermaid-wrapper">
|
|
148
|
+
<div class="mermaid-title">Diagram</div>
|
|
149
|
+
<div class="mermaid">graph LR
|
|
150
|
+
A[Global CLAUDE.md] --> B[Document Standards]
|
|
151
|
+
A --> C[Git Workflow]
|
|
152
|
+
A --> D[Quality Checks]
|
|
153
|
+
A --> E[Security Practices]
|
|
154
|
+
|
|
155
|
+
B --> B1[Naming Conventions]
|
|
156
|
+
B --> B2[Markdown Standards]
|
|
157
|
+
B --> B3[Diagram Requirements]
|
|
158
|
+
|
|
159
|
+
C --> C1[Commit Frequency]
|
|
160
|
+
C --> C2[Branch Strategy]
|
|
161
|
+
|
|
162
|
+
D --> D1[Verification Marks]
|
|
163
|
+
D --> D2[Changelog Updates]
|
|
164
|
+
|
|
165
|
+
E --> E1[No Credentials]
|
|
166
|
+
E --> E2[Access Controls]</div>
|
|
167
|
+
</div>
|
|
168
|
+
<h2>Step 2: Initialize doc-builder</h2>
|
|
169
|
+
<pre><code class="language-bash"># Install doc-builder
|
|
170
|
+
npm install -D @knowcode/doc-builder
|
|
171
|
+
|
|
172
|
+
# Initialize configuration
|
|
173
|
+
npx doc-builder init
|
|
174
|
+
</code></pre>
|
|
175
|
+
<h3>2.1 Configure doc-builder.config.js</h3>
|
|
176
|
+
<pre><code class="language-javascript">module.exports = {
|
|
177
|
+
siteName: 'Your Project Documentation',
|
|
178
|
+
siteDescription: 'Comprehensive documentation for Your Project',
|
|
179
|
+
docsDir: 'docs',
|
|
180
|
+
outputDir: 'html',
|
|
181
|
+
features: {
|
|
182
|
+
authentication: false, // Set true for private docs
|
|
183
|
+
changelog: true,
|
|
184
|
+
mermaid: true,
|
|
185
|
+
darkMode: true
|
|
186
|
+
}
|
|
187
|
+
};
|
|
188
|
+
</code></pre>
|
|
189
|
+
<h2>Step 3: Documentation Creation Workflow with Claude</h2>
|
|
190
|
+
<h3>3.1 Effective Prompting Strategy</h3>
|
|
191
|
+
<div class="mermaid-wrapper">
|
|
192
|
+
<div class="mermaid-title">Diagram</div>
|
|
193
|
+
<div class="mermaid">sequenceDiagram
|
|
194
|
+
participant User
|
|
195
|
+
participant Claude
|
|
196
|
+
participant CLAUDE.md
|
|
197
|
+
participant Documentation
|
|
198
|
+
|
|
199
|
+
User->>Claude: Request documentation
|
|
200
|
+
Claude->>CLAUDE.md: Check project standards
|
|
201
|
+
CLAUDE.md-->>Claude: Return guidelines
|
|
202
|
+
Claude->>Documentation: Create/Update docs
|
|
203
|
+
Claude->>User: Confirm completion
|
|
204
|
+
User->>Claude: Review & refine
|
|
205
|
+
Claude->>Documentation: Apply refinements</div>
|
|
206
|
+
</div>
|
|
207
|
+
<h3>3.2 Example Documentation Requests</h3>
|
|
208
|
+
<h4>Initial Architecture Documentation</h4>
|
|
209
|
+
<pre><code>"Create comprehensive architecture documentation for our authentication system. Include:
|
|
210
|
+
- System overview with mermaid diagrams
|
|
211
|
+
- Component interactions
|
|
212
|
+
- API endpoints
|
|
213
|
+
- Security considerations
|
|
214
|
+
- Deployment architecture"
|
|
215
|
+
</code></pre>
|
|
216
|
+
<h4>API Documentation</h4>
|
|
217
|
+
<pre><code>"Document all REST API endpoints in our user service. For each endpoint include:
|
|
218
|
+
- HTTP method and path
|
|
219
|
+
- Request/response schemas
|
|
220
|
+
- Authentication requirements
|
|
221
|
+
- Example requests with curl
|
|
222
|
+
- Error responses"
|
|
223
|
+
</code></pre>
|
|
224
|
+
<h4>Setup Guide</h4>
|
|
225
|
+
<pre><code>"Create a detailed setup guide for new developers including:
|
|
226
|
+
- Prerequisites
|
|
227
|
+
- Environment setup steps
|
|
228
|
+
- Configuration options
|
|
229
|
+
- Common issues and solutions
|
|
230
|
+
- Development workflow"
|
|
231
|
+
</code></pre>
|
|
232
|
+
<h3>3.3 Claude Interaction Best Practices</h3>
|
|
233
|
+
<ol>
|
|
234
|
+
<li><strong>Be Specific</strong>: Provide clear requirements and expected structure</li>
|
|
235
|
+
<li><strong>Iterate</strong>: Review generated content and request refinements</li>
|
|
236
|
+
<li><strong>Verify</strong>: Ask Claude to mark verified vs speculated information</li>
|
|
237
|
+
<li><strong>Examples</strong>: Request concrete examples and code snippets</li>
|
|
238
|
+
<li><strong>Diagrams</strong>: Explicitly request mermaid diagrams for visual clarity</li>
|
|
239
|
+
</ol>
|
|
240
|
+
<h2>Step 4: Building Documentation Site</h2>
|
|
241
|
+
<h3>4.1 Development Workflow</h3>
|
|
242
|
+
<div class="mermaid-wrapper">
|
|
243
|
+
<div class="mermaid-title">Diagram</div>
|
|
244
|
+
<div class="mermaid">graph LR
|
|
245
|
+
A[Write Docs] --> B[Preview Locally]
|
|
246
|
+
B --> C{Looks Good?}
|
|
247
|
+
C -->|No| A
|
|
248
|
+
C -->|Yes| D[Build Site]
|
|
249
|
+
D --> E[Test Build]
|
|
250
|
+
E --> F{All Good?}
|
|
251
|
+
F -->|No| A
|
|
252
|
+
F -->|Yes| G[Ready to Deploy]
|
|
253
|
+
|
|
254
|
+
style A fill:#fff3e0
|
|
255
|
+
style G fill:#c8e6c9</div>
|
|
256
|
+
</div>
|
|
257
|
+
<h3>4.2 Commands</h3>
|
|
258
|
+
<pre><code class="language-bash"># Start development server
|
|
259
|
+
npm run dev:docs
|
|
260
|
+
|
|
261
|
+
# Build static site
|
|
262
|
+
npm run build:docs
|
|
263
|
+
|
|
264
|
+
# Preview built site
|
|
265
|
+
npx serve html
|
|
266
|
+
</code></pre>
|
|
267
|
+
<h2>Step 5: Deploying to Vercel</h2>
|
|
268
|
+
<h3>5.1 First-Time Setup</h3>
|
|
269
|
+
<pre><code class="language-bash"># Deploy to Vercel (interactive)
|
|
270
|
+
npx doc-builder deploy
|
|
271
|
+
|
|
272
|
+
# Or with npm script
|
|
273
|
+
npm run deploy:docs
|
|
274
|
+
</code></pre>
|
|
275
|
+
<h3>5.2 Vercel Configuration</h3>
|
|
276
|
+
<p>The tool automatically creates <code>vercel.json</code>:</p>
|
|
277
|
+
<pre><code class="language-json">{
|
|
278
|
+
"outputDirectory": "html",
|
|
279
|
+
"routes": [
|
|
280
|
+
{
|
|
281
|
+
"src": "/(.*)",
|
|
282
|
+
"dest": "/$1"
|
|
283
|
+
}
|
|
284
|
+
]
|
|
285
|
+
}
|
|
286
|
+
</code></pre>
|
|
287
|
+
<h3>5.3 Deployment Workflow</h3>
|
|
288
|
+
<div class="mermaid-wrapper">
|
|
289
|
+
<div class="mermaid-title">Diagram</div>
|
|
290
|
+
<div class="mermaid">stateDiagram-v2
|
|
291
|
+
[*] --> LocalDevelopment
|
|
292
|
+
LocalDevelopment --> BuildDocs: npm run build:docs
|
|
293
|
+
BuildDocs --> TestLocally: npx serve html
|
|
294
|
+
TestLocally --> Deploy: npx doc-builder deploy
|
|
295
|
+
Deploy --> VercelProcessing
|
|
296
|
+
VercelProcessing --> LiveSite: Success
|
|
297
|
+
VercelProcessing --> ErrorHandling: Failed
|
|
298
|
+
ErrorHandling --> LocalDevelopment: Fix issues
|
|
299
|
+
LiveSite --> [*]</div>
|
|
300
|
+
</div>
|
|
301
|
+
<h2>Step 6: Continuous Documentation Updates</h2>
|
|
302
|
+
<h3>6.1 Update Workflow</h3>
|
|
303
|
+
<div class="mermaid-wrapper">
|
|
304
|
+
<div class="mermaid-title">Diagram</div>
|
|
305
|
+
<div class="mermaid">graph TD
|
|
306
|
+
A[Code Changes] --> B{Docs Needed?}
|
|
307
|
+
B -->|Yes| C[Update Documentation]
|
|
308
|
+
B -->|No| End[End]
|
|
309
|
+
C --> D[Use Claude for Updates]
|
|
310
|
+
D --> E[Review Changes]
|
|
311
|
+
E --> F[Build & Test]
|
|
312
|
+
F --> G[Deploy Updates]
|
|
313
|
+
G --> H[Update CHANGELOG.md]
|
|
314
|
+
H --> End
|
|
315
|
+
|
|
316
|
+
style A fill:#ffebee
|
|
317
|
+
style G fill:#e8f5e9</div>
|
|
318
|
+
</div>
|
|
319
|
+
<h3>6.2 Maintaining Documentation Quality</h3>
|
|
320
|
+
<ol>
|
|
321
|
+
<li><strong>Regular Reviews</strong>: Schedule periodic documentation reviews</li>
|
|
322
|
+
<li><strong>Automated Checks</strong>: Add documentation linting to CI/CD</li>
|
|
323
|
+
<li><strong>User Feedback</strong>: Create feedback mechanism for documentation</li>
|
|
324
|
+
<li><strong>Version Tracking</strong>: Maintain documentation versions with code versions</li>
|
|
325
|
+
</ol>
|
|
326
|
+
<h2>Advanced CLAUDE.md Refinements</h2>
|
|
327
|
+
<h3>7.1 Project-Specific Instructions</h3>
|
|
328
|
+
<pre><code class="language-markdown">## Project-Specific Documentation Rules
|
|
329
|
+
|
|
330
|
+
### Component Documentation
|
|
331
|
+
- Each major component needs its own guide
|
|
332
|
+
- Include architecture decisions
|
|
333
|
+
- Document integration points
|
|
334
|
+
- Add performance considerations
|
|
335
|
+
|
|
336
|
+
### Code Examples
|
|
337
|
+
- Use TypeScript for all examples
|
|
338
|
+
- Include error handling
|
|
339
|
+
- Show both correct and incorrect usage
|
|
340
|
+
- Add inline comments for clarity
|
|
341
|
+
|
|
342
|
+
### Diagrams
|
|
343
|
+
- Use mermaid for all flow diagrams
|
|
344
|
+
- Include sequence diagrams for APIs
|
|
345
|
+
- Add state diagrams for complex logic
|
|
346
|
+
- Create entity relationship diagrams for data models
|
|
347
|
+
</code></pre>
|
|
348
|
+
<h3>7.2 Documentation Templates</h3>
|
|
349
|
+
<p>Create templates in your CLAUDE.md:</p>
|
|
350
|
+
<pre><code class="language-markdown">## Documentation Templates
|
|
351
|
+
|
|
352
|
+
### API Endpoint Template
|
|
353
|
+
</code></pre>
|
|
354
|
+
<h2>[HTTP Method] /api/[endpoint]</h2>
|
|
355
|
+
<p><strong>Purpose</strong>: [Brief description]</p>
|
|
356
|
+
<h3>Request</h3>
|
|
357
|
+
<ul>
|
|
358
|
+
<li><strong>Headers</strong>: <ul>
|
|
359
|
+
<li><code>Authorization: Bearer [token]</code></li>
|
|
360
|
+
<li><code>Content-Type: application/json</code></li>
|
|
361
|
+
</ul>
|
|
362
|
+
</li>
|
|
363
|
+
<li><strong>Body</strong>:<pre><code class="language-json">{
|
|
364
|
+
"field": "value"
|
|
365
|
+
}
|
|
366
|
+
</code></pre>
|
|
367
|
+
</li>
|
|
368
|
+
</ul>
|
|
369
|
+
<h3>Response</h3>
|
|
370
|
+
<ul>
|
|
371
|
+
<li><strong>Success (200)</strong>:<pre><code class="language-json">{
|
|
372
|
+
"data": {}
|
|
373
|
+
}
|
|
374
|
+
</code></pre>
|
|
375
|
+
</li>
|
|
376
|
+
<li><strong>Error (4xx/5xx)</strong>:<pre><code class="language-json">{
|
|
377
|
+
"error": "Description"
|
|
378
|
+
}
|
|
379
|
+
</code></pre>
|
|
380
|
+
</li>
|
|
381
|
+
</ul>
|
|
382
|
+
<h3>Examples</h3>
|
|
383
|
+
<pre><code class="language-bash">curl -X POST https://api.example.com/endpoint \
|
|
384
|
+
-H "Authorization: Bearer token" \
|
|
385
|
+
-d '{"field": "value"}'
|
|
386
|
+
</code></pre>
|
|
387
|
+
<pre><code>
|
|
388
|
+
## Best Practices Summary
|
|
389
|
+
|
|
390
|
+
### Documentation Creation
|
|
391
|
+
1. ✅ Use CLAUDE.md to maintain consistency
|
|
392
|
+
2. ✅ Include visual diagrams for complex concepts
|
|
393
|
+
3. ✅ Provide practical examples
|
|
394
|
+
4. ✅ Mark verification status
|
|
395
|
+
5. ✅ Keep documentation close to code
|
|
396
|
+
|
|
397
|
+
### Claude Interaction
|
|
398
|
+
1. ✅ Provide clear, specific requests
|
|
399
|
+
2. ✅ Reference existing patterns
|
|
400
|
+
3. ✅ Request iterative improvements
|
|
401
|
+
4. ✅ Verify technical accuracy
|
|
402
|
+
5. ✅ Ask for troubleshooting sections
|
|
403
|
+
|
|
404
|
+
### Deployment
|
|
405
|
+
1. ✅ Test locally before deploying
|
|
406
|
+
2. ✅ Use preview deployments first
|
|
407
|
+
3. ✅ Configure custom domains
|
|
408
|
+
4. ✅ Enable HTTPS
|
|
409
|
+
5. ✅ Monitor deployment health
|
|
410
|
+
|
|
411
|
+
## Common Issues and Solutions
|
|
412
|
+
|
|
413
|
+
### Issue 1: Claude Not Following Standards
|
|
414
|
+
**Solution**: Refine CLAUDE.md with more specific examples and explicit requirements
|
|
415
|
+
|
|
416
|
+
### Issue 2: Documentation Build Fails
|
|
417
|
+
**Solution**: Check markdown syntax, ensure all links are valid, verify mermaid syntax
|
|
418
|
+
|
|
419
|
+
### Issue 3: Vercel Deployment Issues
|
|
420
|
+
**Solution**: Check vercel.json configuration, ensure output directory is correct
|
|
421
|
+
|
|
422
|
+
### Issue 4: Navigation Not Generated
|
|
423
|
+
**Solution**: Verify folder structure follows conventions, check for special characters in filenames
|
|
424
|
+
|
|
425
|
+
## Conclusion
|
|
426
|
+
|
|
427
|
+
This workflow enables efficient, high-quality documentation creation by:
|
|
428
|
+
- Leveraging Claude's capabilities with clear guidelines
|
|
429
|
+
- Using doc-builder for beautiful, searchable output
|
|
430
|
+
- Deploying seamlessly to Vercel for instant access
|
|
431
|
+
- Maintaining consistency through CLAUDE.md refinements
|
|
432
|
+
|
|
433
|
+
The key to success is iterative refinement of your CLAUDE.md file to capture your team's specific documentation needs and standards.
|
|
434
|
+
|
|
435
|
+
## Document History
|
|
436
|
+
|
|
437
|
+
| Date | Author | Changes |
|
|
438
|
+
|------|--------|---------|
|
|
439
|
+
| 2025-07-21 | Claude | Initial creation |
|
|
440
|
+
</code></pre>
|
|
441
|
+
|
|
442
|
+
</div>
|
|
443
|
+
</main>
|
|
444
|
+
</div>
|
|
445
|
+
|
|
446
|
+
<!-- Scripts -->
|
|
447
|
+
<script src="/js/main.js"></script>
|
|
448
|
+
|
|
449
|
+
</body>
|
|
450
|
+
</html>
|
|
@@ -311,27 +311,23 @@ pre code {
|
|
|
311
311
|
|
|
312
312
|
/* Sidebar */
|
|
313
313
|
.sidebar {
|
|
314
|
-
position:
|
|
315
|
-
left: 0;
|
|
316
|
-
top: calc(var(--header-height) + var(--breadcrumb-height));
|
|
317
|
-
bottom: 0;
|
|
314
|
+
position: relative;
|
|
318
315
|
width: var(--sidebar-width);
|
|
319
316
|
background: var(--color-bg-secondary);
|
|
320
317
|
border-right: 1px solid var(--color-border-default);
|
|
321
318
|
overflow: hidden;
|
|
322
|
-
transition:
|
|
319
|
+
transition: width var(--duration-normal);
|
|
323
320
|
min-width: 200px;
|
|
324
321
|
max-width: 500px;
|
|
325
322
|
user-select: none;
|
|
326
323
|
display: flex;
|
|
327
324
|
flex-direction: column;
|
|
328
325
|
z-index: 100;
|
|
326
|
+
flex-shrink: 0;
|
|
327
|
+
height: 100%;
|
|
329
328
|
}
|
|
330
329
|
|
|
331
|
-
/*
|
|
332
|
-
.sidebar.banner-visible {
|
|
333
|
-
top: calc(var(--header-height) + var(--breadcrumb-height) + 3.5rem);
|
|
334
|
-
}
|
|
330
|
+
/* Banner adjustment no longer needed with relative positioning */
|
|
335
331
|
|
|
336
332
|
|
|
337
333
|
.sidebar-home-link {
|
package/html/vercel.json
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
{
|
|
2
|
+
"buildCommand": "",
|
|
3
|
+
"outputDirectory": ".",
|
|
4
|
+
"devCommand": "",
|
|
5
|
+
"installCommand": "",
|
|
6
|
+
"framework": null,
|
|
7
|
+
"cleanUrls": true,
|
|
8
|
+
"trailingSlash": false,
|
|
9
|
+
"headers": [
|
|
10
|
+
{
|
|
11
|
+
"source": "/css/(.*)",
|
|
12
|
+
"headers": [
|
|
13
|
+
{
|
|
14
|
+
"key": "Cache-Control",
|
|
15
|
+
"value": "public, max-age=31536000, immutable"
|
|
16
|
+
}
|
|
17
|
+
]
|
|
18
|
+
},
|
|
19
|
+
{
|
|
20
|
+
"source": "/js/(.*)",
|
|
21
|
+
"headers": [
|
|
22
|
+
{
|
|
23
|
+
"key": "Cache-Control",
|
|
24
|
+
"value": "public, max-age=31536000, immutable"
|
|
25
|
+
}
|
|
26
|
+
]
|
|
27
|
+
}
|
|
28
|
+
]
|
|
29
|
+
}
|
|
Binary file
|
package/lib/core-builder.js
CHANGED
|
@@ -57,7 +57,9 @@ function extractSummary(content, maxLength = 150) {
|
|
|
57
57
|
// Process markdown content
|
|
58
58
|
function processMarkdownContent(content) {
|
|
59
59
|
// Convert mermaid code blocks to mermaid divs with titles
|
|
60
|
-
|
|
60
|
+
// Process before markdown parsing to prevent breaking up the content
|
|
61
|
+
const mermaidBlocks = [];
|
|
62
|
+
let processedContent = content.replace(/```mermaid\n([\s\S]*?)```/g, (match, mermaidContent) => {
|
|
61
63
|
// Try to extract title from mermaid content
|
|
62
64
|
let title = 'Diagram';
|
|
63
65
|
|
|
@@ -77,13 +79,25 @@ function processMarkdownContent(content) {
|
|
|
77
79
|
}
|
|
78
80
|
}
|
|
79
81
|
|
|
80
|
-
return
|
|
82
|
+
// Store the mermaid block and return a placeholder
|
|
83
|
+
const placeholder = `MERMAID_BLOCK_${mermaidBlocks.length}`;
|
|
84
|
+
mermaidBlocks.push(`<div class="mermaid-wrapper">
|
|
81
85
|
<div class="mermaid-title">${escapeHtml(title)}</div>
|
|
82
|
-
<div class="mermaid">${
|
|
83
|
-
</div
|
|
86
|
+
<div class="mermaid">${mermaidContent.trim()}</div>
|
|
87
|
+
</div>`);
|
|
88
|
+
return placeholder;
|
|
89
|
+
});
|
|
90
|
+
|
|
91
|
+
// Parse the markdown
|
|
92
|
+
let html = marked.parse(processedContent);
|
|
93
|
+
|
|
94
|
+
// Replace placeholders with actual mermaid blocks
|
|
95
|
+
mermaidBlocks.forEach((block, index) => {
|
|
96
|
+
html = html.replace(`<p>MERMAID_BLOCK_${index}</p>`, block);
|
|
97
|
+
html = html.replace(`MERMAID_BLOCK_${index}`, block);
|
|
84
98
|
});
|
|
85
99
|
|
|
86
|
-
return
|
|
100
|
+
return html;
|
|
87
101
|
}
|
|
88
102
|
|
|
89
103
|
// Generate HTML from template
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# Cache Busting Guide for @knowcode/doc-builder
|
|
2
|
+
|
|
3
|
+
If you're not seeing updates after upgrading to a new version, it's likely due to caching. Follow these steps:
|
|
4
|
+
|
|
5
|
+
## 1. Clean Everything Locally
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
# Remove old build artifacts
|
|
9
|
+
rm -rf html/
|
|
10
|
+
|
|
11
|
+
# Clear npm cache
|
|
12
|
+
npm cache clean --force
|
|
13
|
+
|
|
14
|
+
# Remove node_modules and reinstall
|
|
15
|
+
rm -rf node_modules
|
|
16
|
+
npm install
|
|
17
|
+
|
|
18
|
+
# Make sure you have the latest version
|
|
19
|
+
npm install @knowcode/doc-builder@latest
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## 2. Rebuild with Fresh Files
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
# Build fresh documentation
|
|
26
|
+
npx @knowcode/doc-builder build
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## 3. Deploy with Force Flag
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
# Force Vercel to ignore cache
|
|
33
|
+
vercel --prod --force
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## 4. Clear Browser Cache
|
|
37
|
+
|
|
38
|
+
- **Chrome/Edge**: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
|
|
39
|
+
- **Firefox**: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
|
|
40
|
+
- **Safari**: Cmd+Option+R
|
|
41
|
+
- Or use Incognito/Private browsing mode
|
|
42
|
+
|
|
43
|
+
## 5. Clear Vercel/CDN Cache (if applicable)
|
|
44
|
+
|
|
45
|
+
If using Vercel:
|
|
46
|
+
1. Go to your project dashboard
|
|
47
|
+
2. Settings → Functions → Purge Cache
|
|
48
|
+
3. Or redeploy with a different domain temporarily
|
|
49
|
+
|
|
50
|
+
## 6. Add Cache Busting to Your Build
|
|
51
|
+
|
|
52
|
+
Edit your `doc-builder.config.js` to add version query strings:
|
|
53
|
+
|
|
54
|
+
```javascript
|
|
55
|
+
module.exports = {
|
|
56
|
+
// ... other config
|
|
57
|
+
cacheBust: true, // This will add ?v=timestamp to CSS/JS files
|
|
58
|
+
};
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Common Issues
|
|
62
|
+
|
|
63
|
+
- **"I updated but nothing changed"** - It's cache. Follow all steps above.
|
|
64
|
+
- **"Tooltips still don't work"** - Clear browser cache and check console for errors
|
|
65
|
+
- **"Spacing is still wrong"** - The CSS is cached. Hard refresh the page.
|
|
66
|
+
|
|
67
|
+
## Verify You Have The Right Version
|
|
68
|
+
|
|
69
|
+
Check the version in your package.json:
|
|
70
|
+
```bash
|
|
71
|
+
npm list @knowcode/doc-builder
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Should show: `@knowcode/doc-builder@1.3.13` or higher.
|
|
75
|
+
|
|
76
|
+
## Still Not Working?
|
|
77
|
+
|
|
78
|
+
1. Open browser DevTools
|
|
79
|
+
2. Go to Network tab
|
|
80
|
+
3. Check "Disable cache" checkbox
|
|
81
|
+
4. Refresh the page
|
|
82
|
+
5. Look at the CSS/JS files being loaded - they should not show "(from cache)"
|