@knowcode/doc-builder 1.9.0 → 1.9.1
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/README.md +2 -0
- package/html/README.html +34 -149
- package/html/css/notion-style.css +13 -394
- package/html/documentation-index.html +17 -127
- package/html/guides/authentication-default-change.html +8 -130
- package/html/guides/authentication-guide.html +20 -141
- package/html/guides/claude-workflow-guide.html +23 -137
- package/html/guides/documentation-standards.html +12 -133
- package/html/guides/image-modal-guide.html +381 -0
- package/html/guides/phosphor-icons-guide.html +28 -150
- package/html/guides/private-directory-authentication.html +8 -130
- package/html/guides/public-site-deployment.html +8 -130
- package/html/guides/search-engine-verification-guide.html +8 -130
- package/html/guides/seo-guide.html +8 -130
- package/html/guides/seo-optimization-guide.html +39 -159
- package/html/guides/troubleshooting-guide.html +20 -141
- package/html/guides/windows-setup-guide.html +39 -161
- package/html/image-modal-test.html +9 -125
- package/html/index.html +34 -149
- package/html/js/auth.js +39 -118
- package/html/js/main.js +25 -259
- package/html/private/cache-control-anti-pattern.html +13 -135
- package/html/private/launch/README.html +16 -144
- package/html/private/launch/auth-cleanup-summary.html +25 -153
- package/html/private/launch/bubble-plugin-specification.html +8 -136
- package/html/private/launch/go-to-market-strategy.html +10 -138
- package/html/private/launch/launch-announcements.html +24 -151
- package/html/private/launch/vercel-deployment-auth-setup.html +10 -138
- package/html/private/next-steps-walkthrough.html +15 -137
- package/html/private/supabase-auth-implementation-completed.html +22 -143
- package/html/private/supabase-auth-implementation-plan.html +15 -136
- package/html/private/supabase-auth-integration-plan.html +22 -142
- package/html/private/supabase-auth-setup-guide.html +17 -139
- package/html/private/test-private-doc.html +8 -130
- package/html/private/user-management-tooling.html +8 -130
- package/html/prompts/markdown-document-standards.html +13 -134
- package/html/vercel-cli-setup-guide.html +12 -128
- package/html/vercel-first-time-setup-guide.html +9 -125
- package/lib/emoji-mapper.js +12 -0
- package/package.json +1 -1
|
@@ -3,41 +3,14 @@
|
|
|
3
3
|
<head>
|
|
4
4
|
<meta charset="UTF-8">
|
|
5
5
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
6
|
-
<meta name="description" content="
|
|
7
|
-
<title>SEO Optimization Guide
|
|
8
|
-
|
|
9
|
-
<meta name="author" content="Lindsay Smith">
|
|
10
|
-
<meta name="keywords" content="documentation, markdown, static site generator, vercel, notion-style, SEO, optimization">
|
|
11
|
-
<meta name="robots" content="index, follow">
|
|
12
|
-
<link rel="canonical" href="https://doc-builder-delta.vercel.app/guides/seo-optimization-guide.html">
|
|
13
|
-
|
|
14
|
-
<!-- Open Graph / Facebook -->
|
|
15
|
-
<meta property="og:type" content="article">
|
|
16
|
-
<meta property="og:url" content="https://doc-builder-delta.vercel.app/guides/seo-optimization-guide.html">
|
|
17
|
-
<meta property="og:title" content="SEO Optimization Guide for @knowcode/doc-builder">
|
|
18
|
-
<meta property="og:description" content="Comprehensive guide to optimizing documentation for search engines. Learn SEO best practices, use built-in features, and improve your rankings.">
|
|
19
|
-
<meta property="og:image" content="https://doc-builder-delta.vercel.app/og-default.png">
|
|
20
|
-
<meta property="og:site_name" content="@knowcode/doc-builder">
|
|
21
|
-
<meta property="og:locale" content="en_US">
|
|
22
|
-
|
|
23
|
-
<!-- Twitter Card -->
|
|
24
|
-
<meta name="twitter:card" content="summary_large_image">
|
|
25
|
-
<meta name="twitter:site" content="@planbbackups">
|
|
26
|
-
<meta name="twitter:creator" content="@planbbackups">
|
|
27
|
-
<meta name="twitter:title" content="SEO Optimization Guide for @knowcode/doc-builder">
|
|
28
|
-
<meta name="twitter:description" content="Comprehensive guide to optimizing documentation for search engines. Learn SEO best practices, use built-in features, and improve your rankings.">
|
|
29
|
-
<meta name="twitter:image" content="https://doc-builder-delta.vercel.app/og-default.png">
|
|
30
|
-
|
|
31
|
-
<!-- Custom Meta Tags -->
|
|
32
|
-
<meta name="google-site-verification" content="FtzcDTf5BQ9K5EfnGazQkgU2U4FiN3ITzM7gHwqUAqQ">
|
|
33
|
-
<meta name="msvalidate.01" content="B2D8C4C12C530D47AA962B24CAA09630">
|
|
6
|
+
<meta name="description" content="Beautiful documentation with the least effort possible">
|
|
7
|
+
<title>SEO Optimization Guide - @knowcode/doc-builder</title>
|
|
34
8
|
|
|
35
9
|
<!-- Fonts -->
|
|
36
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">
|
|
37
11
|
|
|
38
12
|
<!-- Icons -->
|
|
39
13
|
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css">
|
|
40
|
-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@phosphor-icons/web@2.1.1/src/regular/style.css">
|
|
41
14
|
|
|
42
15
|
<!-- Mermaid -->
|
|
43
16
|
<script src="https://cdn.jsdelivr.net/npm/mermaid@10.6.1/dist/mermaid.min.js"></script>
|
|
@@ -45,90 +18,8 @@
|
|
|
45
18
|
<!-- Styles -->
|
|
46
19
|
<link rel="stylesheet" href="/css/notion-style.css">
|
|
47
20
|
|
|
48
|
-
|
|
49
|
-
<!-- Hide content until auth check -->
|
|
50
|
-
<style>
|
|
51
|
-
body {
|
|
52
|
-
visibility: hidden;
|
|
53
|
-
opacity: 0;
|
|
54
|
-
transition: opacity 0.3s ease;
|
|
55
|
-
}
|
|
56
|
-
body.authenticated {
|
|
57
|
-
visibility: visible;
|
|
58
|
-
opacity: 1;
|
|
59
|
-
}
|
|
60
|
-
/* Show login/logout pages immediately */
|
|
61
|
-
body.auth-page {
|
|
62
|
-
visibility: visible;
|
|
63
|
-
opacity: 1;
|
|
64
|
-
}
|
|
65
|
-
/* Style auth button consistently */
|
|
66
|
-
.auth-btn {
|
|
67
|
-
background: none;
|
|
68
|
-
border: none;
|
|
69
|
-
color: var(--text-secondary);
|
|
70
|
-
cursor: pointer;
|
|
71
|
-
padding: 0.5rem;
|
|
72
|
-
border-radius: 0.5rem;
|
|
73
|
-
transition: all 0.2s;
|
|
74
|
-
font-size: 1.1rem;
|
|
75
|
-
}
|
|
76
|
-
.auth-btn:hover {
|
|
77
|
-
background: var(--bg-secondary);
|
|
78
|
-
color: var(--text-primary);
|
|
79
|
-
}
|
|
80
|
-
</style>
|
|
81
|
-
|
|
82
|
-
|
|
83
21
|
<!-- Favicon -->
|
|
84
|
-
<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
|
|
85
|
-
|
|
86
|
-
<script type="application/ld+json">
|
|
87
|
-
{
|
|
88
|
-
"@context": "https://schema.org",
|
|
89
|
-
"@type": "TechArticle",
|
|
90
|
-
"headline": "SEO Optimization Guide for @knowcode/doc-builder",
|
|
91
|
-
"description": "Comprehensive guide to optimizing documentation for search engines. Learn SEO best practices, use built-in features, and improve your rankings.",
|
|
92
|
-
"author": {
|
|
93
|
-
"@type": "Person",
|
|
94
|
-
"name": "Lindsay Smith"
|
|
95
|
-
},
|
|
96
|
-
"publisher": {
|
|
97
|
-
"@type": "Organization",
|
|
98
|
-
"name": "Knowcode Ltd",
|
|
99
|
-
"url": "https://knowcode.tech"
|
|
100
|
-
},
|
|
101
|
-
"datePublished": "2025-07-27T08:30:10.797Z",
|
|
102
|
-
"dateModified": "2025-07-27T08:30:10.797Z",
|
|
103
|
-
"mainEntityOfPage": {
|
|
104
|
-
"@type": "WebPage",
|
|
105
|
-
"@id": "https://doc-builder-delta.vercel.app/guides/seo-optimization-guide.html"
|
|
106
|
-
},
|
|
107
|
-
"breadcrumb": {
|
|
108
|
-
"@type": "BreadcrumbList",
|
|
109
|
-
"itemListElement": [
|
|
110
|
-
{
|
|
111
|
-
"@type": "ListItem",
|
|
112
|
-
"position": 1,
|
|
113
|
-
"name": "@knowcode/doc-builder",
|
|
114
|
-
"item": "https://doc-builder-delta.vercel.app"
|
|
115
|
-
},
|
|
116
|
-
{
|
|
117
|
-
"@type": "ListItem",
|
|
118
|
-
"position": 2,
|
|
119
|
-
"name": "Guides",
|
|
120
|
-
"item": "https://doc-builder-delta.vercel.app/guides/"
|
|
121
|
-
},
|
|
122
|
-
{
|
|
123
|
-
"@type": "ListItem",
|
|
124
|
-
"position": 3,
|
|
125
|
-
"name": "Seo Optimization Guide",
|
|
126
|
-
"item": "https://doc-builder-delta.vercel.app/guides/seo-optimization-guide.html"
|
|
127
|
-
}
|
|
128
|
-
]
|
|
129
|
-
}
|
|
130
|
-
}
|
|
131
|
-
</script>
|
|
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>">
|
|
132
23
|
</head>
|
|
133
24
|
<body>
|
|
134
25
|
<!-- Header -->
|
|
@@ -138,14 +29,10 @@
|
|
|
138
29
|
|
|
139
30
|
<div class="header-actions">
|
|
140
31
|
<div class="deployment-info">
|
|
141
|
-
<span class="deployment-date" title="Built with doc-builder v1.
|
|
32
|
+
<span class="deployment-date" title="Built with doc-builder v1.4.21">Last updated: Jul 27, 2025, 08:32 AM UTC</span>
|
|
142
33
|
</div>
|
|
143
34
|
|
|
144
35
|
|
|
145
|
-
<a href="../../login.html" class="auth-btn" title="Login/Logout">
|
|
146
|
-
<i class="fas fa-sign-in-alt"></i>
|
|
147
|
-
</a>
|
|
148
|
-
|
|
149
36
|
|
|
150
37
|
<button id="theme-toggle" class="theme-toggle" aria-label="Toggle theme">
|
|
151
38
|
<i class="fas fa-moon"></i>
|
|
@@ -205,6 +92,7 @@
|
|
|
205
92
|
<a href="/guides/authentication-guide.html" class="nav-item" data-tooltip="@knowcode/doc-builder supports enterprise-grade authentication through Supabase - a secure, scalable authentication platform."><i class="fas fa-file-alt"></i> Authentication Guide</a>
|
|
206
93
|
<a href="/guides/claude-workflow-guide.html" class="nav-item" data-tooltip="This guide demonstrates an efficient workflow for using Claude Code with a refined CLAUDE.md file to create high-quality documentation and deploy it..."><i class="fas fa-file-alt"></i> Claude Workflow Guide</a>
|
|
207
94
|
<a href="/guides/documentation-standards.html" class="nav-item" data-tooltip="This document defines the documentation standards and conventions for the @knowcode/doc-builder project."><i class="fas fa-file-alt"></i> Documentation Standards</a>
|
|
95
|
+
<a href="/guides/image-modal-guide.html" class="nav-item" data-tooltip="When users click on any image in your generated documentation, it opens in a professional modal overlay with: Full-screen viewing experience Smooth..."><i class="fas fa-file-alt"></i> Image Modal Guide</a>
|
|
208
96
|
<a href="/guides/phosphor-icons-guide.html" class="nav-item" data-tooltip="@knowcode/doc-builder automatically converts Unicode emojis in your markdown files to beautiful Phosphor icons in the generated HTML."><i class="fas fa-file-alt"></i> Phosphor Icons Guide</a>
|
|
209
97
|
<a href="/guides/private-directory-authentication.html" class="nav-item" data-tooltip="The @knowcode/doc-builder provides flexible authentication options to protect your documentation."><i class="fas fa-file-alt"></i> Private Directory Authentication</a>
|
|
210
98
|
<a href="/guides/public-site-deployment.html" class="nav-item" data-tooltip="The @knowcode/doc-builder now supports deploying public documentation sites without authentication."><i class="fas fa-file-alt"></i> Public Site Deployment</a>
|
|
@@ -213,7 +101,7 @@
|
|
|
213
101
|
<a href="/guides/seo-optimization-guide.html" class="nav-item active" data-tooltip="@knowcode/doc-builder includes comprehensive SEO (Search Engine Optimization) features that automatically optimize your documentation for search..."><i class="fas fa-file-alt"></i> Seo Optimization Guide</a>
|
|
214
102
|
<a href="/guides/troubleshooting-guide.html" class="nav-item" data-tooltip="This guide helps you resolve common issues when using @knowcode/doc-builder."><i class="fas fa-file-alt"></i> Troubleshooting Guide</a>
|
|
215
103
|
<a href="/guides/windows-setup-guide.html" class="nav-item" data-tooltip="This guide helps Windows users set up the complete AI-powered documentation workflow using Claude Code, @knowcode/doc-builder, and Vercel."><i class="fas fa-file-alt"></i> Windows Setup Guide</a></div></div>
|
|
216
|
-
<div class="nav-section
|
|
104
|
+
<div class="nav-section" data-level="1">
|
|
217
105
|
<a class="nav-title collapsible" href="#" data-target="nav-private-1" >
|
|
218
106
|
<i class="fas fa-chevron-right collapse-icon"></i><i class="fas fa-folder"></i> Private
|
|
219
107
|
</a>
|
|
@@ -226,7 +114,7 @@
|
|
|
226
114
|
<a href="/private/supabase-auth-setup-guide.html" class="nav-item" data-tooltip="@knowcode/doc-builder supports enterprise-grade authentication through Supabase."><i class="fas fa-file-alt"></i> Supabase Auth Setup Guide</a>
|
|
227
115
|
<a href="/private/test-private-doc.html" class="nav-item" data-tooltip="Test Private Document."><i class="fas fa-file-alt"></i> Test Private Doc</a>
|
|
228
116
|
<a href="/private/user-management-tooling.html" class="nav-item" data-tooltip="The user management system is a set of tools designed to manage user access to Supabase-authenticated documentation sites built with."><i class="fas fa-file-alt"></i> User Management Tooling</a></div></div>
|
|
229
|
-
<div class="nav-section
|
|
117
|
+
<div class="nav-section" data-level="2">
|
|
230
118
|
<a class="nav-title collapsible" href="/private/launch/README.html" data-target="nav-private-launch-2" >
|
|
231
119
|
<i class="fas fa-chevron-right collapse-icon"></i><i class="fas fa-folder"></i> Launch
|
|
232
120
|
</a>
|
|
@@ -250,7 +138,9 @@
|
|
|
250
138
|
<!-- Content Area -->
|
|
251
139
|
<main class="content">
|
|
252
140
|
<div class="content-inner">
|
|
253
|
-
<
|
|
141
|
+
<hr>
|
|
142
|
+
<h2>title: "SEO Optimization Guide for @knowcode/doc-builder"<br>description: "Comprehensive guide to optimizing documentation for search engines. Learn SEO best practices, use built-in features, and improve your rankings."<br>keywords: ["SEO", "documentation", "optimization", "front matter", "meta tags", "search engines", "doc-builder"]<br>author: "Doc Builder Team"<br>date: "2025-07-22"</h2>
|
|
143
|
+
<h1>SEO Optimization Guide</h1>
|
|
254
144
|
<h2>Overview</h2>
|
|
255
145
|
<p>@knowcode/doc-builder includes comprehensive SEO (Search Engine Optimization) features that automatically optimize your documentation for search engines. This guide explains what these features do, how to use them effectively, and provides references to authoritative SEO resources.</p>
|
|
256
146
|
<h2>Why SEO Matters for Documentation</h2>
|
|
@@ -384,15 +274,15 @@ keywords: ["authentication", "security", "password prot
|
|
|
384
274
|
<h3>Examples</h3>
|
|
385
275
|
<p>Good titles:</p>
|
|
386
276
|
<ul>
|
|
387
|
-
<li
|
|
388
|
-
<li
|
|
389
|
-
<li
|
|
277
|
+
<li>✅ "Authentication Guide | Doc Builder" (38 chars)</li>
|
|
278
|
+
<li>✅ "SEO Best Practices for Documentation | MyDocs" (45 chars)</li>
|
|
279
|
+
<li>✅ "Quick Start: Deploy to Vercel | Doc Builder" (43 chars)</li>
|
|
390
280
|
</ul>
|
|
391
281
|
<p>Bad titles:</p>
|
|
392
282
|
<ul>
|
|
393
|
-
<li
|
|
394
|
-
<li
|
|
395
|
-
<li
|
|
283
|
+
<li>❌ "Guide" (5 chars - too short)</li>
|
|
284
|
+
<li>❌ "The Complete Comprehensive Guide to Setting Up Authentication and Security for Your Documentation Website | Doc Builder" (118 chars - too long)</li>
|
|
285
|
+
<li>❌ "Page Title | Site Name | Category | Subcategory" (keyword stuffing)</li>
|
|
396
286
|
</ul>
|
|
397
287
|
<h2>Meta Descriptions</h2>
|
|
398
288
|
<h3>Best Practices</h3>
|
|
@@ -414,13 +304,13 @@ keywords: ["authentication", "security", "password prot
|
|
|
414
304
|
<h3>Examples</h3>
|
|
415
305
|
<p>Good descriptions:</p>
|
|
416
306
|
<ul>
|
|
417
|
-
<li
|
|
418
|
-
<li
|
|
307
|
+
<li>✅ "Learn how to implement authentication in your documentation site. Step-by-step guide with code examples and security best practices." (139 chars)</li>
|
|
308
|
+
<li>✅ "Optimize your documentation for search engines with our comprehensive SEO guide. Covers titles, descriptions, and keyword strategies." (143 chars)</li>
|
|
419
309
|
</ul>
|
|
420
310
|
<p>Bad descriptions:</p>
|
|
421
311
|
<ul>
|
|
422
|
-
<li
|
|
423
|
-
<li
|
|
312
|
+
<li>❌ "This page is about authentication." (35 chars - too short)</li>
|
|
313
|
+
<li>❌ "Authentication authentication authentication..." (keyword stuffing)</li>
|
|
424
314
|
</ul>
|
|
425
315
|
<h2>Keywords Strategy</h2>
|
|
426
316
|
<h3>Modern Keyword Approach (2025)</h3>
|
|
@@ -464,14 +354,14 @@ doc-builder seo-check html/guide.html
|
|
|
464
354
|
<h3>What It Analyzes in HTML</h3>
|
|
465
355
|
<p>The command inspects the actual HTML output that search engines see:</p>
|
|
466
356
|
<ul>
|
|
467
|
-
<li
|
|
468
|
-
<li
|
|
469
|
-
<li
|
|
470
|
-
<li
|
|
471
|
-
<li
|
|
472
|
-
<li
|
|
473
|
-
<li
|
|
474
|
-
<li
|
|
357
|
+
<li>✅ <strong>Title tags</strong> - Presence and optimal length (50-60 chars)</li>
|
|
358
|
+
<li>✅ <strong>Meta descriptions</strong> - Quality and character count (140-160)</li>
|
|
359
|
+
<li>✅ <strong>Keywords meta tag</strong> - Presence of relevant keywords</li>
|
|
360
|
+
<li>✅ <strong>Canonical URLs</strong> - Prevents duplicate content penalties</li>
|
|
361
|
+
<li>✅ <strong>H1 tags</strong> - Ensures proper heading structure</li>
|
|
362
|
+
<li>✅ <strong>Open Graph tags</strong> - Social media optimization</li>
|
|
363
|
+
<li>✅ <strong>Twitter Card tags</strong> - Twitter/X optimization</li>
|
|
364
|
+
<li>✅ <strong>Structured data</strong> - JSON-LD implementation</li>
|
|
475
365
|
</ul>
|
|
476
366
|
<h3>Example Output</h3>
|
|
477
367
|
<pre><code>🔍 Analyzing SEO in generated HTML files...
|
|
@@ -554,28 +444,28 @@ Your content here...
|
|
|
554
444
|
<h2>Common SEO Mistakes to Avoid</h2>
|
|
555
445
|
<h3>1. Duplicate Content</h3>
|
|
556
446
|
<ul>
|
|
557
|
-
<li
|
|
558
|
-
<li
|
|
447
|
+
<li>❌ Same description on multiple pages</li>
|
|
448
|
+
<li>✅ Unique descriptions for each page</li>
|
|
559
449
|
</ul>
|
|
560
450
|
<h3>2. Keyword Stuffing</h3>
|
|
561
451
|
<ul>
|
|
562
|
-
<li
|
|
563
|
-
<li
|
|
452
|
+
<li>❌ "Guide guide documentation guide tutorial guide"</li>
|
|
453
|
+
<li>✅ Natural keyword usage in context</li>
|
|
564
454
|
</ul>
|
|
565
455
|
<h3>3. Ignoring Mobile</h3>
|
|
566
456
|
<ul>
|
|
567
|
-
<li
|
|
568
|
-
<li
|
|
457
|
+
<li>❌ Long titles that get cut off on mobile</li>
|
|
458
|
+
<li>✅ Test how titles appear on different devices</li>
|
|
569
459
|
</ul>
|
|
570
460
|
<h3>4. Missing Descriptions</h3>
|
|
571
461
|
<ul>
|
|
572
|
-
<li
|
|
573
|
-
<li
|
|
462
|
+
<li>❌ Leaving description blank</li>
|
|
463
|
+
<li>✅ Always provide meaningful descriptions</li>
|
|
574
464
|
</ul>
|
|
575
465
|
<h3>5. Generic Titles</h3>
|
|
576
466
|
<ul>
|
|
577
|
-
<li
|
|
578
|
-
<li
|
|
467
|
+
<li>❌ "Documentation", "Guide", "Page 1"</li>
|
|
468
|
+
<li>✅ Specific, descriptive titles</li>
|
|
579
469
|
</ul>
|
|
580
470
|
<h2>SEO Checklist</h2>
|
|
581
471
|
<p>Before publishing, ensure:</p>
|
|
@@ -858,17 +748,7 @@ doc-builder deploy
|
|
|
858
748
|
</div>
|
|
859
749
|
|
|
860
750
|
<!-- Scripts -->
|
|
861
|
-
<script>
|
|
862
|
-
// Pass configuration to frontend
|
|
863
|
-
window.docBuilderConfig = {
|
|
864
|
-
features: {
|
|
865
|
-
showPdfDownload: true,
|
|
866
|
-
menuDefaultOpen: false
|
|
867
|
-
}
|
|
868
|
-
};
|
|
869
|
-
</script>
|
|
870
751
|
<script src="/js/main.js"></script>
|
|
871
|
-
|
|
872
|
-
<script src="/js/auth.js"></script>
|
|
752
|
+
|
|
873
753
|
</body>
|
|
874
754
|
</html>
|
|
@@ -3,41 +3,14 @@
|
|
|
3
3
|
<head>
|
|
4
4
|
<meta charset="UTF-8">
|
|
5
5
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
6
|
-
<meta name="description" content="
|
|
7
|
-
<title>Troubleshooting Guide for @knowcode/doc-builder</title>
|
|
8
|
-
|
|
9
|
-
<meta name="author" content="Lindsay Smith">
|
|
10
|
-
<meta name="keywords" content="documentation, markdown, static site generator, vercel, notion-style, issues, check">
|
|
11
|
-
<meta name="robots" content="index, follow">
|
|
12
|
-
<link rel="canonical" href="https://doc-builder-delta.vercel.app/guides/troubleshooting-guide.html">
|
|
13
|
-
|
|
14
|
-
<!-- Open Graph / Facebook -->
|
|
15
|
-
<meta property="og:type" content="article">
|
|
16
|
-
<meta property="og:url" content="https://doc-builder-delta.vercel.app/guides/troubleshooting-guide.html">
|
|
17
|
-
<meta property="og:title" content="Troubleshooting Guide for @knowcode/doc-builder">
|
|
18
|
-
<meta property="og:description" content="This guide helps you resolve common issues when using @knowcode/doc-builder. Most problems have simple solutions, and this guide covers the most frequent ones.">
|
|
19
|
-
<meta property="og:image" content="https://doc-builder-delta.vercel.app/og-default.png">
|
|
20
|
-
<meta property="og:site_name" content="@knowcode/doc-builder">
|
|
21
|
-
<meta property="og:locale" content="en_US">
|
|
22
|
-
|
|
23
|
-
<!-- Twitter Card -->
|
|
24
|
-
<meta name="twitter:card" content="summary_large_image">
|
|
25
|
-
<meta name="twitter:site" content="@planbbackups">
|
|
26
|
-
<meta name="twitter:creator" content="@planbbackups">
|
|
27
|
-
<meta name="twitter:title" content="Troubleshooting Guide for @knowcode/doc-builder">
|
|
28
|
-
<meta name="twitter:description" content="This guide helps you resolve common issues when using @knowcode/doc-builder. Most problems have simple solutions, and this guide covers the most frequent ones.">
|
|
29
|
-
<meta name="twitter:image" content="https://doc-builder-delta.vercel.app/og-default.png">
|
|
30
|
-
|
|
31
|
-
<!-- Custom Meta Tags -->
|
|
32
|
-
<meta name="google-site-verification" content="FtzcDTf5BQ9K5EfnGazQkgU2U4FiN3ITzM7gHwqUAqQ">
|
|
33
|
-
<meta name="msvalidate.01" content="B2D8C4C12C530D47AA962B24CAA09630">
|
|
6
|
+
<meta name="description" content="Beautiful documentation with the least effort possible">
|
|
7
|
+
<title>Troubleshooting Guide for @knowcode/doc-builder - @knowcode/doc-builder</title>
|
|
34
8
|
|
|
35
9
|
<!-- Fonts -->
|
|
36
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">
|
|
37
11
|
|
|
38
12
|
<!-- Icons -->
|
|
39
13
|
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css">
|
|
40
|
-
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@phosphor-icons/web@2.1.1/src/regular/style.css">
|
|
41
14
|
|
|
42
15
|
<!-- Mermaid -->
|
|
43
16
|
<script src="https://cdn.jsdelivr.net/npm/mermaid@10.6.1/dist/mermaid.min.js"></script>
|
|
@@ -45,90 +18,8 @@
|
|
|
45
18
|
<!-- Styles -->
|
|
46
19
|
<link rel="stylesheet" href="/css/notion-style.css">
|
|
47
20
|
|
|
48
|
-
|
|
49
|
-
<!-- Hide content until auth check -->
|
|
50
|
-
<style>
|
|
51
|
-
body {
|
|
52
|
-
visibility: hidden;
|
|
53
|
-
opacity: 0;
|
|
54
|
-
transition: opacity 0.3s ease;
|
|
55
|
-
}
|
|
56
|
-
body.authenticated {
|
|
57
|
-
visibility: visible;
|
|
58
|
-
opacity: 1;
|
|
59
|
-
}
|
|
60
|
-
/* Show login/logout pages immediately */
|
|
61
|
-
body.auth-page {
|
|
62
|
-
visibility: visible;
|
|
63
|
-
opacity: 1;
|
|
64
|
-
}
|
|
65
|
-
/* Style auth button consistently */
|
|
66
|
-
.auth-btn {
|
|
67
|
-
background: none;
|
|
68
|
-
border: none;
|
|
69
|
-
color: var(--text-secondary);
|
|
70
|
-
cursor: pointer;
|
|
71
|
-
padding: 0.5rem;
|
|
72
|
-
border-radius: 0.5rem;
|
|
73
|
-
transition: all 0.2s;
|
|
74
|
-
font-size: 1.1rem;
|
|
75
|
-
}
|
|
76
|
-
.auth-btn:hover {
|
|
77
|
-
background: var(--bg-secondary);
|
|
78
|
-
color: var(--text-primary);
|
|
79
|
-
}
|
|
80
|
-
</style>
|
|
81
|
-
|
|
82
|
-
|
|
83
21
|
<!-- Favicon -->
|
|
84
|
-
<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
|
|
85
|
-
|
|
86
|
-
<script type="application/ld+json">
|
|
87
|
-
{
|
|
88
|
-
"@context": "https://schema.org",
|
|
89
|
-
"@type": "TechArticle",
|
|
90
|
-
"headline": "Troubleshooting Guide for @knowcode/doc-builder",
|
|
91
|
-
"description": "This guide helps you resolve common issues when using @knowcode/doc-builder. Most problems have simple solutions, and this guide covers the most frequent ones.",
|
|
92
|
-
"author": {
|
|
93
|
-
"@type": "Person",
|
|
94
|
-
"name": "Lindsay Smith"
|
|
95
|
-
},
|
|
96
|
-
"publisher": {
|
|
97
|
-
"@type": "Organization",
|
|
98
|
-
"name": "Knowcode Ltd",
|
|
99
|
-
"url": "https://knowcode.tech"
|
|
100
|
-
},
|
|
101
|
-
"datePublished": "2025-07-27T08:30:10.799Z",
|
|
102
|
-
"dateModified": "2025-07-27T08:30:10.799Z",
|
|
103
|
-
"mainEntityOfPage": {
|
|
104
|
-
"@type": "WebPage",
|
|
105
|
-
"@id": "https://doc-builder-delta.vercel.app/guides/troubleshooting-guide.html"
|
|
106
|
-
},
|
|
107
|
-
"breadcrumb": {
|
|
108
|
-
"@type": "BreadcrumbList",
|
|
109
|
-
"itemListElement": [
|
|
110
|
-
{
|
|
111
|
-
"@type": "ListItem",
|
|
112
|
-
"position": 1,
|
|
113
|
-
"name": "@knowcode/doc-builder",
|
|
114
|
-
"item": "https://doc-builder-delta.vercel.app"
|
|
115
|
-
},
|
|
116
|
-
{
|
|
117
|
-
"@type": "ListItem",
|
|
118
|
-
"position": 2,
|
|
119
|
-
"name": "Guides",
|
|
120
|
-
"item": "https://doc-builder-delta.vercel.app/guides/"
|
|
121
|
-
},
|
|
122
|
-
{
|
|
123
|
-
"@type": "ListItem",
|
|
124
|
-
"position": 3,
|
|
125
|
-
"name": "Troubleshooting Guide",
|
|
126
|
-
"item": "https://doc-builder-delta.vercel.app/guides/troubleshooting-guide.html"
|
|
127
|
-
}
|
|
128
|
-
]
|
|
129
|
-
}
|
|
130
|
-
}
|
|
131
|
-
</script>
|
|
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>">
|
|
132
23
|
</head>
|
|
133
24
|
<body>
|
|
134
25
|
<!-- Header -->
|
|
@@ -138,14 +29,10 @@
|
|
|
138
29
|
|
|
139
30
|
<div class="header-actions">
|
|
140
31
|
<div class="deployment-info">
|
|
141
|
-
<span class="deployment-date" title="Built with doc-builder v1.
|
|
32
|
+
<span class="deployment-date" title="Built with doc-builder v1.4.21">Last updated: Jul 27, 2025, 08:32 AM UTC</span>
|
|
142
33
|
</div>
|
|
143
34
|
|
|
144
35
|
|
|
145
|
-
<a href="../../login.html" class="auth-btn" title="Login/Logout">
|
|
146
|
-
<i class="fas fa-sign-in-alt"></i>
|
|
147
|
-
</a>
|
|
148
|
-
|
|
149
36
|
|
|
150
37
|
<button id="theme-toggle" class="theme-toggle" aria-label="Toggle theme">
|
|
151
38
|
<i class="fas fa-moon"></i>
|
|
@@ -205,6 +92,7 @@
|
|
|
205
92
|
<a href="/guides/authentication-guide.html" class="nav-item" data-tooltip="@knowcode/doc-builder supports enterprise-grade authentication through Supabase - a secure, scalable authentication platform."><i class="fas fa-file-alt"></i> Authentication Guide</a>
|
|
206
93
|
<a href="/guides/claude-workflow-guide.html" class="nav-item" data-tooltip="This guide demonstrates an efficient workflow for using Claude Code with a refined CLAUDE.md file to create high-quality documentation and deploy it..."><i class="fas fa-file-alt"></i> Claude Workflow Guide</a>
|
|
207
94
|
<a href="/guides/documentation-standards.html" class="nav-item" data-tooltip="This document defines the documentation standards and conventions for the @knowcode/doc-builder project."><i class="fas fa-file-alt"></i> Documentation Standards</a>
|
|
95
|
+
<a href="/guides/image-modal-guide.html" class="nav-item" data-tooltip="When users click on any image in your generated documentation, it opens in a professional modal overlay with: Full-screen viewing experience Smooth..."><i class="fas fa-file-alt"></i> Image Modal Guide</a>
|
|
208
96
|
<a href="/guides/phosphor-icons-guide.html" class="nav-item" data-tooltip="@knowcode/doc-builder automatically converts Unicode emojis in your markdown files to beautiful Phosphor icons in the generated HTML."><i class="fas fa-file-alt"></i> Phosphor Icons Guide</a>
|
|
209
97
|
<a href="/guides/private-directory-authentication.html" class="nav-item" data-tooltip="The @knowcode/doc-builder provides flexible authentication options to protect your documentation."><i class="fas fa-file-alt"></i> Private Directory Authentication</a>
|
|
210
98
|
<a href="/guides/public-site-deployment.html" class="nav-item" data-tooltip="The @knowcode/doc-builder now supports deploying public documentation sites without authentication."><i class="fas fa-file-alt"></i> Public Site Deployment</a>
|
|
@@ -213,7 +101,7 @@
|
|
|
213
101
|
<a href="/guides/seo-optimization-guide.html" class="nav-item" data-tooltip="@knowcode/doc-builder includes comprehensive SEO (Search Engine Optimization) features that automatically optimize your documentation for search..."><i class="fas fa-file-alt"></i> Seo Optimization Guide</a>
|
|
214
102
|
<a href="/guides/troubleshooting-guide.html" class="nav-item active" data-tooltip="This guide helps you resolve common issues when using @knowcode/doc-builder."><i class="fas fa-file-alt"></i> Troubleshooting Guide</a>
|
|
215
103
|
<a href="/guides/windows-setup-guide.html" class="nav-item" data-tooltip="This guide helps Windows users set up the complete AI-powered documentation workflow using Claude Code, @knowcode/doc-builder, and Vercel."><i class="fas fa-file-alt"></i> Windows Setup Guide</a></div></div>
|
|
216
|
-
<div class="nav-section
|
|
104
|
+
<div class="nav-section" data-level="1">
|
|
217
105
|
<a class="nav-title collapsible" href="#" data-target="nav-private-1" >
|
|
218
106
|
<i class="fas fa-chevron-right collapse-icon"></i><i class="fas fa-folder"></i> Private
|
|
219
107
|
</a>
|
|
@@ -226,7 +114,7 @@
|
|
|
226
114
|
<a href="/private/supabase-auth-setup-guide.html" class="nav-item" data-tooltip="@knowcode/doc-builder supports enterprise-grade authentication through Supabase."><i class="fas fa-file-alt"></i> Supabase Auth Setup Guide</a>
|
|
227
115
|
<a href="/private/test-private-doc.html" class="nav-item" data-tooltip="Test Private Document."><i class="fas fa-file-alt"></i> Test Private Doc</a>
|
|
228
116
|
<a href="/private/user-management-tooling.html" class="nav-item" data-tooltip="The user management system is a set of tools designed to manage user access to Supabase-authenticated documentation sites built with."><i class="fas fa-file-alt"></i> User Management Tooling</a></div></div>
|
|
229
|
-
<div class="nav-section
|
|
117
|
+
<div class="nav-section" data-level="2">
|
|
230
118
|
<a class="nav-title collapsible" href="/private/launch/README.html" data-target="nav-private-launch-2" >
|
|
231
119
|
<i class="fas fa-chevron-right collapse-icon"></i><i class="fas fa-folder"></i> Launch
|
|
232
120
|
</a>
|
|
@@ -258,10 +146,10 @@
|
|
|
258
146
|
<p>The most common issue users face is npx caching an older version of doc-builder.</p>
|
|
259
147
|
<p><strong>Symptoms:</strong></p>
|
|
260
148
|
<ul>
|
|
261
|
-
<li
|
|
262
|
-
<li
|
|
263
|
-
<li
|
|
264
|
-
<li
|
|
149
|
+
<li>❌ Running <code>npx @knowcode/doc-builder</code> shows an old version number</li>
|
|
150
|
+
<li>❌ New features aren't available despite updating</li>
|
|
151
|
+
<li>❌ Bug fixes don't appear to be working</li>
|
|
152
|
+
<li>❌ Version shown doesn't match npm registry</li>
|
|
265
153
|
</ul>
|
|
266
154
|
<p><strong>Example:</strong></p>
|
|
267
155
|
<pre><code class="language-bash">$ npx @knowcode/doc-builder@latest --version
|
|
@@ -283,6 +171,7 @@ npx @knowcode/doc-builder@1.4.22
|
|
|
283
171
|
</code></pre>
|
|
284
172
|
<h3>Why This Happens</h3>
|
|
285
173
|
<div class="mermaid-wrapper">
|
|
174
|
+
<div class="mermaid-title">Diagram</div>
|
|
286
175
|
<div class="mermaid">graph TD
|
|
287
176
|
A[Run npx @knowcode/doc-builder] --> B{Package in cache?}
|
|
288
177
|
B -->|Yes| C[Use cached version]
|
|
@@ -324,10 +213,10 @@ npx doc-builder deploy # Uses local version
|
|
|
324
213
|
</li>
|
|
325
214
|
<li><p><strong>Ensure correct file extensions:</strong></p>
|
|
326
215
|
<ul>
|
|
327
|
-
<li
|
|
328
|
-
<li
|
|
329
|
-
<li
|
|
330
|
-
<li
|
|
216
|
+
<li>✅ <code>README.md</code></li>
|
|
217
|
+
<li>✅ <code>guide.md</code></li>
|
|
218
|
+
<li>❌ <code>README.txt</code></li>
|
|
219
|
+
<li>❌ <code>guide.markdown</code></li>
|
|
331
220
|
</ul>
|
|
332
221
|
</li>
|
|
333
222
|
<li><p><strong>Use custom input directory:</strong></p>
|
|
@@ -407,9 +296,9 @@ npx @knowcode/doc-builder@latest set-production-url https://my-docs.vercel.app
|
|
|
407
296
|
<ol>
|
|
408
297
|
<li><p><strong>Check file name:</strong></p>
|
|
409
298
|
<ul>
|
|
410
|
-
<li
|
|
411
|
-
<li
|
|
412
|
-
<li
|
|
299
|
+
<li>✅ <code>doc-builder.config.js</code></li>
|
|
300
|
+
<li>❌ <code>docbuilder.config.js</code></li>
|
|
301
|
+
<li>❌ <code>doc-builder-config.js</code></li>
|
|
413
302
|
</ul>
|
|
414
303
|
</li>
|
|
415
304
|
<li><p><strong>Verify export format:</strong></p>
|
|
@@ -604,17 +493,7 @@ npm --version
|
|
|
604
493
|
</div>
|
|
605
494
|
|
|
606
495
|
<!-- Scripts -->
|
|
607
|
-
<script>
|
|
608
|
-
// Pass configuration to frontend
|
|
609
|
-
window.docBuilderConfig = {
|
|
610
|
-
features: {
|
|
611
|
-
showPdfDownload: true,
|
|
612
|
-
menuDefaultOpen: false
|
|
613
|
-
}
|
|
614
|
-
};
|
|
615
|
-
</script>
|
|
616
496
|
<script src="/js/main.js"></script>
|
|
617
|
-
|
|
618
|
-
<script src="/js/auth.js"></script>
|
|
497
|
+
|
|
619
498
|
</body>
|
|
620
499
|
</html>
|