@knowcode/doc-builder 1.8.7 → 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/.claude/settings.local.json +2 -1
- package/CHANGELOG.md +27 -0
- package/README.md +2 -0
- package/assets/css/notion-style.css +141 -0
- package/assets/js/main.js +76 -0
- package/html/README.html +41 -149
- package/html/css/notion-style.css +13 -253
- package/html/documentation-index.html +24 -127
- package/html/guides/authentication-default-change.html +15 -130
- package/html/guides/authentication-guide.html +27 -141
- package/html/guides/claude-workflow-guide.html +30 -137
- package/html/guides/documentation-standards.html +19 -133
- package/html/guides/image-modal-guide.html +381 -0
- package/html/guides/phosphor-icons-guide.html +35 -150
- package/html/guides/private-directory-authentication.html +15 -130
- package/html/guides/public-site-deployment.html +15 -130
- package/html/guides/search-engine-verification-guide.html +15 -130
- package/html/guides/seo-guide.html +15 -130
- package/html/guides/seo-optimization-guide.html +46 -159
- package/html/guides/troubleshooting-guide.html +27 -141
- package/html/guides/windows-setup-guide.html +46 -161
- package/html/image-modal-test.html +189 -0
- package/html/index.html +41 -149
- package/html/js/auth.js +39 -118
- package/html/js/main.js +25 -183
- package/html/private/cache-control-anti-pattern.html +20 -135
- package/html/private/launch/README.html +23 -144
- package/html/private/launch/auth-cleanup-summary.html +32 -153
- package/html/private/launch/bubble-plugin-specification.html +15 -136
- package/html/private/launch/go-to-market-strategy.html +17 -138
- package/html/private/launch/launch-announcements.html +31 -151
- package/html/private/launch/vercel-deployment-auth-setup.html +17 -138
- package/html/private/next-steps-walkthrough.html +21 -136
- package/html/private/supabase-auth-implementation-completed.html +29 -143
- package/html/private/supabase-auth-implementation-plan.html +22 -136
- package/html/private/supabase-auth-integration-plan.html +29 -142
- package/html/private/supabase-auth-setup-guide.html +24 -139
- package/html/private/test-private-doc.html +15 -130
- package/html/private/user-management-tooling.html +15 -130
- package/html/prompts/markdown-document-standards.html +288 -0
- package/html/sitemap.xml +56 -44
- package/html/vercel-cli-setup-guide.html +19 -128
- package/html/vercel-first-time-setup-guide.html +16 -125
- package/lib/core-builder.js +1 -0
- package/lib/emoji-mapper.js +25 -0
- package/package/assets/css/notion-style.css +432 -135
- package/package/assets/js/main.js +259 -25
- package/package.json +1 -1
package/html/js/main.js
CHANGED
|
@@ -79,6 +79,9 @@ function initializeMermaidFullScreen() {
|
|
|
79
79
|
const toolbar = document.createElement('div');
|
|
80
80
|
toolbar.className = 'mermaid-toolbar';
|
|
81
81
|
|
|
82
|
+
const title = document.createElement('div');
|
|
83
|
+
title.textContent = 'Mermaid Diagram';
|
|
84
|
+
|
|
82
85
|
const actions = document.createElement('div');
|
|
83
86
|
actions.className = 'mermaid-actions';
|
|
84
87
|
|
|
@@ -88,8 +91,23 @@ function initializeMermaidFullScreen() {
|
|
|
88
91
|
fullScreenBtn.innerHTML = '<i class="fas fa-expand"></i> Full Screen';
|
|
89
92
|
fullScreenBtn.addEventListener('click', () => openMermaidFullScreen(mermaidDiv, index));
|
|
90
93
|
|
|
94
|
+
// Copy SVG button
|
|
95
|
+
const copyBtn = document.createElement('button');
|
|
96
|
+
copyBtn.className = 'mermaid-btn';
|
|
97
|
+
copyBtn.innerHTML = '<i class="fas fa-copy"></i> Copy SVG';
|
|
98
|
+
copyBtn.addEventListener('click', () => copyMermaidSVG(mermaidDiv));
|
|
99
|
+
|
|
100
|
+
// Copy Mermaid source button
|
|
101
|
+
const copyMermaidBtn = document.createElement('button');
|
|
102
|
+
copyMermaidBtn.className = 'mermaid-btn';
|
|
103
|
+
copyMermaidBtn.innerHTML = '<i class="fas fa-code"></i> Copy Mermaid';
|
|
104
|
+
copyMermaidBtn.addEventListener('click', () => copyMermaidSource(mermaidDiv));
|
|
105
|
+
|
|
91
106
|
actions.appendChild(fullScreenBtn);
|
|
107
|
+
actions.appendChild(copyBtn);
|
|
108
|
+
actions.appendChild(copyMermaidBtn);
|
|
92
109
|
|
|
110
|
+
toolbar.appendChild(title);
|
|
93
111
|
toolbar.appendChild(actions);
|
|
94
112
|
|
|
95
113
|
// Create wrapper for the diagram
|
|
@@ -494,147 +512,12 @@ function updateThemeIcon(theme) {
|
|
|
494
512
|
const menuToggle = document.getElementById('menu-toggle');
|
|
495
513
|
const sidebar = document.querySelector('.sidebar');
|
|
496
514
|
|
|
497
|
-
// Set initial menu state based on configuration
|
|
498
|
-
const menuDefaultOpen = window.docBuilderConfig?.features?.menuDefaultOpen !== false;
|
|
499
|
-
if (sidebar && window.innerWidth > 768) {
|
|
500
|
-
if (!menuDefaultOpen) {
|
|
501
|
-
sidebar.classList.add('closed');
|
|
502
|
-
// Add class to body to show menu toggle on desktop when menu starts closed
|
|
503
|
-
document.body.classList.add('menu-starts-closed');
|
|
504
|
-
}
|
|
505
|
-
}
|
|
506
|
-
|
|
507
|
-
// Create overlay element for mobile
|
|
508
|
-
let overlay = document.querySelector('.sidebar-overlay');
|
|
509
|
-
if (!overlay && window.innerWidth <= 768) {
|
|
510
|
-
overlay = document.createElement('div');
|
|
511
|
-
overlay.className = 'sidebar-overlay';
|
|
512
|
-
document.body.appendChild(overlay);
|
|
513
|
-
}
|
|
514
|
-
|
|
515
515
|
if (menuToggle) {
|
|
516
516
|
menuToggle.addEventListener('click', () => {
|
|
517
|
-
if (window.innerWidth <= 768) {
|
|
518
|
-
// Mobile: toggle 'open' class
|
|
519
|
-
sidebar.classList.toggle('open');
|
|
520
|
-
} else {
|
|
521
|
-
// Desktop: toggle 'closed' class
|
|
522
|
-
sidebar.classList.toggle('closed');
|
|
523
|
-
// Update visibility of menu toggle based on sidebar state
|
|
524
|
-
updateMenuToggleVisibility();
|
|
525
|
-
}
|
|
526
|
-
if (overlay) {
|
|
527
|
-
overlay.classList.toggle('active');
|
|
528
|
-
}
|
|
529
|
-
});
|
|
530
|
-
}
|
|
531
|
-
|
|
532
|
-
// Function to update menu toggle visibility
|
|
533
|
-
function updateMenuToggleVisibility() {
|
|
534
|
-
if (window.innerWidth > 768) {
|
|
535
|
-
if (!menuDefaultOpen || sidebar.classList.contains('closed')) {
|
|
536
|
-
document.body.classList.add('show-menu-toggle');
|
|
537
|
-
} else {
|
|
538
|
-
document.body.classList.remove('show-menu-toggle');
|
|
539
|
-
}
|
|
540
|
-
}
|
|
541
|
-
}
|
|
542
|
-
|
|
543
|
-
// Initial check
|
|
544
|
-
updateMenuToggleVisibility();
|
|
545
|
-
|
|
546
|
-
// Update on window resize
|
|
547
|
-
window.addEventListener('resize', updateMenuToggleVisibility);
|
|
548
|
-
|
|
549
|
-
// Close menu when clicking overlay
|
|
550
|
-
if (overlay) {
|
|
551
|
-
overlay.addEventListener('click', () => {
|
|
552
|
-
sidebar.classList.remove('open');
|
|
553
|
-
overlay.classList.remove('active');
|
|
554
|
-
});
|
|
555
|
-
}
|
|
556
|
-
|
|
557
|
-
// Floating Menu Button for Mobile
|
|
558
|
-
function initFloatingMenuButton() {
|
|
559
|
-
// Only initialize on mobile
|
|
560
|
-
if (window.innerWidth > 768) return;
|
|
561
|
-
|
|
562
|
-
// Check if button already exists
|
|
563
|
-
if (document.getElementById('floating-menu-toggle')) return;
|
|
564
|
-
|
|
565
|
-
// Create floating button
|
|
566
|
-
const floatingButton = document.createElement('button');
|
|
567
|
-
floatingButton.id = 'floating-menu-toggle';
|
|
568
|
-
floatingButton.className = 'floating-menu-toggle';
|
|
569
|
-
floatingButton.setAttribute('aria-label', 'Toggle menu');
|
|
570
|
-
floatingButton.innerHTML = '<i class="fas fa-bars"></i>';
|
|
571
|
-
floatingButton.style.display = 'flex'; // Always visible on mobile
|
|
572
|
-
floatingButton.classList.add('visible'); // Start visible
|
|
573
|
-
|
|
574
|
-
// Add to body
|
|
575
|
-
document.body.appendChild(floatingButton);
|
|
576
|
-
|
|
577
|
-
// Toggle sidebar on click
|
|
578
|
-
floatingButton.addEventListener('click', () => {
|
|
579
517
|
sidebar.classList.toggle('open');
|
|
580
|
-
|
|
581
|
-
// Handle overlay
|
|
582
|
-
let overlay = document.querySelector('.sidebar-overlay');
|
|
583
|
-
if (!overlay) {
|
|
584
|
-
overlay = document.createElement('div');
|
|
585
|
-
overlay.className = 'sidebar-overlay';
|
|
586
|
-
document.body.appendChild(overlay);
|
|
587
|
-
|
|
588
|
-
// Add overlay click handler
|
|
589
|
-
overlay.addEventListener('click', () => {
|
|
590
|
-
sidebar.classList.remove('open');
|
|
591
|
-
overlay.classList.remove('active');
|
|
592
|
-
floatingButton.querySelector('i').className = 'fas fa-bars';
|
|
593
|
-
});
|
|
594
|
-
}
|
|
595
|
-
|
|
596
|
-
if (overlay) {
|
|
597
|
-
overlay.classList.toggle('active');
|
|
598
|
-
}
|
|
599
|
-
|
|
600
|
-
// Update icon based on state
|
|
601
|
-
const icon = floatingButton.querySelector('i');
|
|
602
|
-
if (sidebar.classList.contains('open')) {
|
|
603
|
-
icon.className = 'fas fa-times';
|
|
604
|
-
} else {
|
|
605
|
-
icon.className = 'fas fa-bars';
|
|
606
|
-
}
|
|
607
|
-
});
|
|
608
|
-
|
|
609
|
-
// Remove scroll-based visibility - button is always visible on mobile
|
|
610
|
-
|
|
611
|
-
// Update icon when sidebar state changes from other sources
|
|
612
|
-
const observer = new MutationObserver(() => {
|
|
613
|
-
const icon = floatingButton.querySelector('i');
|
|
614
|
-
if (sidebar.classList.contains('open')) {
|
|
615
|
-
icon.className = 'fas fa-times';
|
|
616
|
-
} else {
|
|
617
|
-
icon.className = 'fas fa-bars';
|
|
618
|
-
}
|
|
619
|
-
});
|
|
620
|
-
|
|
621
|
-
observer.observe(sidebar, {
|
|
622
|
-
attributes: true,
|
|
623
|
-
attributeFilter: ['class']
|
|
624
518
|
});
|
|
625
519
|
}
|
|
626
520
|
|
|
627
|
-
// Initialize floating button on load and resize
|
|
628
|
-
document.addEventListener('DOMContentLoaded', initFloatingMenuButton);
|
|
629
|
-
window.addEventListener('resize', () => {
|
|
630
|
-
const existingButton = document.getElementById('floating-menu-toggle');
|
|
631
|
-
if (window.innerWidth > 768 && existingButton) {
|
|
632
|
-
existingButton.remove();
|
|
633
|
-
} else if (window.innerWidth <= 768 && !existingButton) {
|
|
634
|
-
initFloatingMenuButton();
|
|
635
|
-
}
|
|
636
|
-
});
|
|
637
|
-
|
|
638
521
|
// Prevent sidebar from closing when clicking nav items
|
|
639
522
|
// Only close when clicking outside the sidebar or the close button
|
|
640
523
|
document.addEventListener('click', (e) => {
|
|
@@ -642,21 +525,11 @@ document.addEventListener('click', (e) => {
|
|
|
642
525
|
if (window.innerWidth <= 768) {
|
|
643
526
|
const isClickInsideSidebar = sidebar && sidebar.contains(e.target);
|
|
644
527
|
const isMenuToggle = e.target.closest('#menu-toggle');
|
|
645
|
-
const isFloatingButton = e.target.closest('#floating-menu-toggle');
|
|
646
528
|
const isNavItem = e.target.closest('.nav-item, .nav-title');
|
|
647
|
-
const overlay = document.querySelector('.sidebar-overlay');
|
|
648
529
|
|
|
649
530
|
// Close sidebar only if clicking outside AND not on menu toggle AND not on nav items
|
|
650
|
-
if (!isClickInsideSidebar && !isMenuToggle && !
|
|
531
|
+
if (!isClickInsideSidebar && !isMenuToggle && !isNavItem && sidebar?.classList.contains('open')) {
|
|
651
532
|
sidebar.classList.remove('open');
|
|
652
|
-
if (overlay) {
|
|
653
|
-
overlay.classList.remove('active');
|
|
654
|
-
}
|
|
655
|
-
// Update floating button icon if it exists
|
|
656
|
-
const floatingBtn = document.getElementById('floating-menu-toggle');
|
|
657
|
-
if (floatingBtn) {
|
|
658
|
-
floatingBtn.querySelector('i').className = 'fas fa-bars';
|
|
659
|
-
}
|
|
660
533
|
}
|
|
661
534
|
}
|
|
662
535
|
});
|
|
@@ -665,16 +538,12 @@ document.addEventListener('click', (e) => {
|
|
|
665
538
|
document.querySelectorAll('a[href^="#"]').forEach(anchor => {
|
|
666
539
|
anchor.addEventListener('click', function (e) {
|
|
667
540
|
e.preventDefault();
|
|
668
|
-
const
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
behavior: 'smooth',
|
|
675
|
-
block: 'start'
|
|
676
|
-
});
|
|
677
|
-
}
|
|
541
|
+
const target = document.querySelector(this.getAttribute('href'));
|
|
542
|
+
if (target) {
|
|
543
|
+
target.scrollIntoView({
|
|
544
|
+
behavior: 'smooth',
|
|
545
|
+
block: 'start'
|
|
546
|
+
});
|
|
678
547
|
}
|
|
679
548
|
});
|
|
680
549
|
});
|
|
@@ -1317,10 +1186,6 @@ function exportToPDF() {
|
|
|
1317
1186
|
|
|
1318
1187
|
// Add PDF export button functionality
|
|
1319
1188
|
function addPDFExportButton() {
|
|
1320
|
-
// Check configuration - default to true if not set
|
|
1321
|
-
const showPdfDownload = window.docBuilderConfig?.features?.showPdfDownload !== false;
|
|
1322
|
-
if (!showPdfDownload) return;
|
|
1323
|
-
|
|
1324
1189
|
const headerActions = document.querySelector('.header-actions');
|
|
1325
1190
|
if (headerActions) {
|
|
1326
1191
|
const pdfButton = document.createElement('button');
|
|
@@ -1453,31 +1318,8 @@ function initTooltips() {
|
|
|
1453
1318
|
});
|
|
1454
1319
|
}
|
|
1455
1320
|
|
|
1456
|
-
// Handle .md link redirects
|
|
1457
|
-
function initMarkdownLinkRedirects() {
|
|
1458
|
-
// Check if current URL ends with .md and redirect
|
|
1459
|
-
if (window.location.pathname.endsWith('.md')) {
|
|
1460
|
-
const htmlPath = window.location.pathname.replace(/\.md$/, '.html');
|
|
1461
|
-
console.log(`Redirecting from .md to .html: ${htmlPath}`);
|
|
1462
|
-
window.location.replace(htmlPath);
|
|
1463
|
-
return; // Stop execution as we're redirecting
|
|
1464
|
-
}
|
|
1465
|
-
|
|
1466
|
-
// Intercept clicks on .md links
|
|
1467
|
-
document.addEventListener('click', function(e) {
|
|
1468
|
-
const link = e.target.closest('a');
|
|
1469
|
-
if (link && link.href && link.href.endsWith('.md')) {
|
|
1470
|
-
e.preventDefault();
|
|
1471
|
-
const htmlUrl = link.href.replace(/\.md$/, '.html');
|
|
1472
|
-
console.log(`Converting .md link to .html: ${htmlUrl}`);
|
|
1473
|
-
window.location.href = htmlUrl;
|
|
1474
|
-
}
|
|
1475
|
-
});
|
|
1476
|
-
}
|
|
1477
|
-
|
|
1478
1321
|
// Initialize on DOM Load
|
|
1479
1322
|
document.addEventListener('DOMContentLoaded', () => {
|
|
1480
|
-
initMarkdownLinkRedirects();
|
|
1481
1323
|
highlightNavigation();
|
|
1482
1324
|
generateTableOfContents();
|
|
1483
1325
|
initSidebarResize();
|
|
@@ -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>Cache Control Anti-Pattern: Why Aggressive
|
|
8
|
-
|
|
9
|
-
<meta name="author" content="Lindsay Smith">
|
|
10
|
-
<meta name="keywords" content="documentation, markdown, static site generator, vercel, notion-style, cache, caching">
|
|
11
|
-
<meta name="robots" content="index, follow">
|
|
12
|
-
<link rel="canonical" href="https://doc-builder-delta.vercel.app/private/cache-control-anti-pattern.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/private/cache-control-anti-pattern.html">
|
|
17
|
-
<meta property="og:title" content="Cache Control Anti-Pattern: Why Aggressive Cach...">
|
|
18
|
-
<meta property="og:description" content="This guide documents how to implement aggressive cache-busting headers in doc-builder, but we strongly recommend against using this approach. This...">
|
|
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="Cache Control Anti-Pattern: Why Aggressive Cach...">
|
|
28
|
-
<meta name="twitter:description" content="This guide documents how to implement aggressive cache-busting headers in doc-builder, but we strongly recommend against using this approach. This...">
|
|
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>Cache Control Anti-Pattern: Why Aggressive Cache-Busting is Bad for Documentation Sites - @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": "Cache Control Anti-Pattern: Why Aggressive Cache-Busting is Bad for Documentation Sites",
|
|
91
|
-
"description": "This guide documents how to implement aggressive cache-busting headers in doc-builder, but we strongly recommend against using this approach. This...",
|
|
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-26T16:10:10.632Z",
|
|
102
|
-
"dateModified": "2025-07-26T16:10:10.632Z",
|
|
103
|
-
"mainEntityOfPage": {
|
|
104
|
-
"@type": "WebPage",
|
|
105
|
-
"@id": "https://doc-builder-delta.vercel.app/private/cache-control-anti-pattern.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": "Private",
|
|
120
|
-
"item": "https://doc-builder-delta.vercel.app/private/"
|
|
121
|
-
},
|
|
122
|
-
{
|
|
123
|
-
"@type": "ListItem",
|
|
124
|
-
"position": 3,
|
|
125
|
-
"name": "Cache Control Anti Pattern",
|
|
126
|
-
"item": "https://doc-builder-delta.vercel.app/private/cache-control-anti-pattern.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>
|
|
@@ -193,6 +80,7 @@
|
|
|
193
80
|
<div class="nav-content" >
|
|
194
81
|
<a href="/README.html" class="nav-item" data-tooltip="@knowcode/doc-builder."><i class="fas fa-file-alt"></i> Overview</a>
|
|
195
82
|
<a href="/documentation-index.html" class="nav-item" data-tooltip="This directory contains additional documentation for the @knowcode/doc-builder project, organized by topic and purpose."><i class="fas fa-file-alt"></i> Documentation Index</a>
|
|
83
|
+
<a href="/image-modal-test.html" class="nav-item" data-tooltip="This document tests the new image modal functionality in doc-builder."><i class="fas fa-file-alt"></i> Image Modal Test</a>
|
|
196
84
|
<a href="/vercel-cli-setup-guide.html" class="nav-item" data-tooltip="This guide provides comprehensive instructions for installing the Vercel CLI across different operating systems."><i class="fas fa-file-alt"></i> Vercel Cli Setup Guide</a>
|
|
197
85
|
<a href="/vercel-first-time-setup-guide.html" class="nav-item" data-tooltip="This guide walks you through the Vercel deployment process when using ."><i class="fas fa-file-alt"></i> Vercel First Time Setup Guide</a></div></div>
|
|
198
86
|
<div class="nav-section" data-level="1">
|
|
@@ -204,6 +92,7 @@
|
|
|
204
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>
|
|
205
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>
|
|
206
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>
|
|
207
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>
|
|
208
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>
|
|
209
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>
|
|
@@ -212,7 +101,7 @@
|
|
|
212
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>
|
|
213
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>
|
|
214
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>
|
|
215
|
-
<div class="nav-section
|
|
104
|
+
<div class="nav-section" data-level="1">
|
|
216
105
|
<a class="nav-title collapsible expanded" href="#" data-target="nav-private-1" >
|
|
217
106
|
<i class="fas fa-chevron-right collapse-icon"></i><i class="fas fa-folder"></i> Private
|
|
218
107
|
</a>
|
|
@@ -225,7 +114,7 @@
|
|
|
225
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>
|
|
226
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>
|
|
227
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>
|
|
228
|
-
<div class="nav-section
|
|
117
|
+
<div class="nav-section" data-level="2">
|
|
229
118
|
<a class="nav-title collapsible" href="/private/launch/README.html" data-target="nav-private-launch-2" >
|
|
230
119
|
<i class="fas fa-chevron-right collapse-icon"></i><i class="fas fa-folder"></i> Launch
|
|
231
120
|
</a>
|
|
@@ -236,6 +125,12 @@
|
|
|
236
125
|
<a href="/private/launch/go-to-market-strategy.html" class="nav-item" data-tooltip="Go-to-Market Strategy & Product Launch Plan."><i class="fas fa-file-alt"></i> Go To Market Strategy</a>
|
|
237
126
|
<a href="/private/launch/launch-announcements.html" class="nav-item" data-tooltip="This document contains ready-to-use announcement templates for launching @knowcode/doc-builder across various platforms and channels."><i class="fas fa-file-alt"></i> Launch Announcements</a>
|
|
238
127
|
<a href="/private/launch/vercel-deployment-auth-setup.html" class="nav-item" data-tooltip="Vercel Deployment Authentication Setup Guide."><i class="fas fa-file-alt"></i> Vercel Deployment Auth Setup</a></div></div>
|
|
128
|
+
<div class="nav-section" data-level="1">
|
|
129
|
+
<a class="nav-title collapsible" href="#" data-target="nav-prompts-1" >
|
|
130
|
+
<i class="fas fa-chevron-right collapse-icon"></i><i class="fas fa-folder"></i> Prompts
|
|
131
|
+
</a>
|
|
132
|
+
<div class="nav-content collapsed" id="nav-prompts-1">
|
|
133
|
+
<a href="/prompts/markdown-document-standards.html" class="nav-item" data-tooltip="Detailed introduction to the topic..."><i class="fas fa-file-alt"></i> Markdown Document Standards</a></div></div>
|
|
239
134
|
</nav>
|
|
240
135
|
<div class="resize-handle"></div>
|
|
241
136
|
</aside>
|
|
@@ -244,7 +139,7 @@
|
|
|
244
139
|
<main class="content">
|
|
245
140
|
<div class="content-inner">
|
|
246
141
|
<h1>Cache Control Anti-Pattern: Why Aggressive Cache-Busting is Bad for Documentation Sites</h1>
|
|
247
|
-
<h2
|
|
142
|
+
<h2>⚠️ Important Notice</h2>
|
|
248
143
|
<p>This guide documents how to implement aggressive cache-busting headers in doc-builder, but <strong>we strongly recommend against using this approach</strong>. This documentation exists for educational purposes and to explain why this is considered an anti-pattern for static documentation sites.</p>
|
|
249
144
|
<h2>Why Cache-Busting is a Bad Idea for Documentation</h2>
|
|
250
145
|
<h3>1. Performance Degradation</h3>
|
|
@@ -375,10 +270,10 @@ module.exports = {
|
|
|
375
270
|
<h2>Conclusion</h2>
|
|
376
271
|
<p>Aggressive cache-busting is an anti-pattern for documentation sites. The performance and user experience costs far outweigh any benefits. Instead:</p>
|
|
377
272
|
<ol>
|
|
378
|
-
<li
|
|
379
|
-
<li
|
|
380
|
-
<li
|
|
381
|
-
<li
|
|
273
|
+
<li>✅ Use intelligent caching strategies</li>
|
|
274
|
+
<li>✅ Implement version-based cache busting for assets</li>
|
|
275
|
+
<li>✅ Trust browsers to handle HTML caching appropriately</li>
|
|
276
|
+
<li>❌ Don't disable caching entirely</li>
|
|
382
277
|
</ol>
|
|
383
278
|
<p>Remember: Documentation sites are meant to be fast, reliable, and accessible. Proper caching is essential to achieving these goals.</p>
|
|
384
279
|
<h2>See Also</h2>
|
|
@@ -393,17 +288,7 @@ module.exports = {
|
|
|
393
288
|
</div>
|
|
394
289
|
|
|
395
290
|
<!-- Scripts -->
|
|
396
|
-
<script>
|
|
397
|
-
// Pass configuration to frontend
|
|
398
|
-
window.docBuilderConfig = {
|
|
399
|
-
features: {
|
|
400
|
-
showPdfDownload: true,
|
|
401
|
-
menuDefaultOpen: false
|
|
402
|
-
}
|
|
403
|
-
};
|
|
404
|
-
</script>
|
|
405
291
|
<script src="/js/main.js"></script>
|
|
406
|
-
|
|
407
|
-
<script src="/js/auth.js"></script>
|
|
292
|
+
|
|
408
293
|
</body>
|
|
409
294
|
</html>
|