@knowcode/doc-builder 1.2.6 ā 1.2.8
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/CHANGELOG.md +40 -0
- package/README.md +11 -11
- package/assets/css/style.css +1 -1
- package/assets/js/main.js +1 -2
- package/cli.js +2 -2
- package/lib/config.js +8 -8
- package/lib/core-builder.js +209 -14
- package/lib/deploy.js +51 -9
- package/package.json +3 -3
- package/scripts/setup.js +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -5,6 +5,46 @@ All notable changes to @knowcode/doc-builder will be documented in this file.
|
|
|
5
5
|
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
6
|
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
7
|
|
|
8
|
+
## [1.2.8] - 2025-07-19
|
|
9
|
+
|
|
10
|
+
### Changed
|
|
11
|
+
- Removed all JUNO references from documentation and code
|
|
12
|
+
- Renamed `cybersolstice` preset to `notion-inspired`
|
|
13
|
+
- Updated folder descriptions to be more generic
|
|
14
|
+
- Changed default username from 'juno' to 'admin' in preset
|
|
15
|
+
- Removed `juno-docs` binary alias from package.json
|
|
16
|
+
- Updated keywords to remove 'juno' and add 'notion-style'
|
|
17
|
+
- Cleaned up all internal references to use @knowcode/doc-builder
|
|
18
|
+
|
|
19
|
+
### Fixed
|
|
20
|
+
- Documentation now correctly references @knowcode/doc-builder instead of @juno/doc-builder
|
|
21
|
+
- Updated GitHub URLs to use knowcode organization
|
|
22
|
+
|
|
23
|
+
## [1.2.7] - 2025-07-19
|
|
24
|
+
|
|
25
|
+
### Added
|
|
26
|
+
- Comprehensive debugging output showing package version and file existence checks
|
|
27
|
+
- Support for `index.md` as primary source for index.html (higher priority than README.md)
|
|
28
|
+
- Informative default index.html page when no README.md or index.md exists
|
|
29
|
+
- List of available HTML files in default index page
|
|
30
|
+
- Version and debug information in generated pages
|
|
31
|
+
|
|
32
|
+
### Fixed
|
|
33
|
+
- Fixed infinite redirect loop in deploy.js when no README.html exists
|
|
34
|
+
- Improved index.html creation reliability with better file detection
|
|
35
|
+
- Better error messages and guidance when documentation is missing
|
|
36
|
+
|
|
37
|
+
### Changed
|
|
38
|
+
- Enhanced logging throughout build and deploy processes
|
|
39
|
+
- Redirect to first available HTML file instead of infinite loop
|
|
40
|
+
- More descriptive console output during index.html creation
|
|
41
|
+
|
|
42
|
+
## [1.2.6] - 2025-07-19
|
|
43
|
+
|
|
44
|
+
### Fixed
|
|
45
|
+
- **Index.html creation** - Fixed root URL not serving documentation by creating index.html from README.html
|
|
46
|
+
- Added index.html creation in both build and deploy processes for reliability
|
|
47
|
+
|
|
8
48
|
## [1.2.5] - 2025-07-19
|
|
9
49
|
|
|
10
50
|
### Fixed
|
package/README.md
CHANGED
|
@@ -32,12 +32,12 @@ No installation needed! Just run:
|
|
|
32
32
|
|
|
33
33
|
```bash
|
|
34
34
|
# Build and deploy to Vercel (default action)
|
|
35
|
-
npx @
|
|
35
|
+
npx @knowcode/doc-builder
|
|
36
36
|
|
|
37
37
|
# Or use specific commands:
|
|
38
|
-
npx @
|
|
39
|
-
npx @
|
|
40
|
-
npx @
|
|
38
|
+
npx @knowcode/doc-builder build # Build HTML files only
|
|
39
|
+
npx @knowcode/doc-builder dev # Start development server
|
|
40
|
+
npx @knowcode/doc-builder deploy # Deploy to Vercel
|
|
41
41
|
```
|
|
42
42
|
|
|
43
43
|
The default action (no command specified) will build your documentation and deploy it to Vercel.
|
|
@@ -47,7 +47,7 @@ The default action (no command specified) will build your documentation and depl
|
|
|
47
47
|
For faster execution and offline use:
|
|
48
48
|
|
|
49
49
|
```bash
|
|
50
|
-
npm install --save-dev @
|
|
50
|
+
npm install --save-dev @knowcode/doc-builder
|
|
51
51
|
```
|
|
52
52
|
|
|
53
53
|
Then use shorter commands:
|
|
@@ -108,10 +108,10 @@ module.exports = {
|
|
|
108
108
|
|
|
109
109
|
## Presets
|
|
110
110
|
|
|
111
|
-
Use the `
|
|
111
|
+
Use the `notion-inspired` preset for a clean, modern documentation style:
|
|
112
112
|
|
|
113
113
|
```bash
|
|
114
|
-
npx @
|
|
114
|
+
npx @knowcode/doc-builder build --preset notion-inspired
|
|
115
115
|
```
|
|
116
116
|
|
|
117
117
|
## Commands
|
|
@@ -133,7 +133,7 @@ Options:
|
|
|
133
133
|
Examples:
|
|
134
134
|
doc-builder build # Build with defaults
|
|
135
135
|
doc-builder build --input docs --output dist
|
|
136
|
-
doc-builder build --preset
|
|
136
|
+
doc-builder build --preset notion-inspired # Use Notion-inspired preset
|
|
137
137
|
doc-builder build --config my-config.js # Use custom config
|
|
138
138
|
```
|
|
139
139
|
|
|
@@ -218,7 +218,7 @@ While developing the doc-builder:
|
|
|
218
218
|
npm link
|
|
219
219
|
|
|
220
220
|
# In your other project
|
|
221
|
-
npm link @
|
|
221
|
+
npm link @knowcode/doc-builder
|
|
222
222
|
```
|
|
223
223
|
|
|
224
224
|
### Option 2: File Reference
|
|
@@ -228,7 +228,7 @@ In your project's `package.json`:
|
|
|
228
228
|
```json
|
|
229
229
|
{
|
|
230
230
|
"devDependencies": {
|
|
231
|
-
"@
|
|
231
|
+
"@knowcode/doc-builder": "file:../path/to/doc-builder"
|
|
232
232
|
}
|
|
233
233
|
}
|
|
234
234
|
```
|
|
@@ -240,7 +240,7 @@ Once published:
|
|
|
240
240
|
```json
|
|
241
241
|
{
|
|
242
242
|
"devDependencies": {
|
|
243
|
-
"@
|
|
243
|
+
"@knowcode/doc-builder": "git+https://github.com/knowcode/doc-builder.git"
|
|
244
244
|
}
|
|
245
245
|
}
|
|
246
246
|
```
|
package/assets/css/style.css
CHANGED
package/assets/js/main.js
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
//
|
|
1
|
+
// Documentation Builder - Main JavaScript
|
|
2
2
|
|
|
3
3
|
// Preview Banner Management
|
|
4
4
|
// Set up banner state immediately to prevent flash
|
|
@@ -1261,7 +1261,6 @@ function generateBreadcrumbs() {
|
|
|
1261
1261
|
.map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
|
|
1262
1262
|
.join(' ')
|
|
1263
1263
|
.replace(/\b(Api|Html|Css|Js|Pdf|Qa|Ai)\b/g, (match) => match.toUpperCase())
|
|
1264
|
-
.replace(/\bJuno\b/g, 'JUNO')
|
|
1265
1264
|
.replace(/\bReadme\b/g, 'Overview');
|
|
1266
1265
|
|
|
1267
1266
|
// Get appropriate icon based on segment
|
package/cli.js
CHANGED
|
@@ -66,7 +66,7 @@ program
|
|
|
66
66
|
.option('-c, --config <path>', 'path to config file (default: doc-builder.config.js)')
|
|
67
67
|
.option('-i, --input <dir>', 'input directory containing markdown files (default: docs)')
|
|
68
68
|
.option('-o, --output <dir>', 'output directory for HTML files (default: html)')
|
|
69
|
-
.option('--preset <preset>', 'use a preset configuration (available:
|
|
69
|
+
.option('--preset <preset>', 'use a preset configuration (available: notion-inspired)')
|
|
70
70
|
.option('--legacy', 'use legacy mode for backward compatibility')
|
|
71
71
|
.option('--no-auth', 'disable authentication even if configured')
|
|
72
72
|
.option('--no-changelog', 'disable automatic changelog generation')
|
|
@@ -74,7 +74,7 @@ program
|
|
|
74
74
|
${chalk.yellow('Examples:')}
|
|
75
75
|
${chalk.gray('$')} doc-builder build ${chalk.gray('# Build with defaults')}
|
|
76
76
|
${chalk.gray('$')} doc-builder build --input docs --output dist
|
|
77
|
-
${chalk.gray('$')} doc-builder build --preset
|
|
77
|
+
${chalk.gray('$')} doc-builder build --preset notion-inspired ${chalk.gray('# Use Notion-inspired preset')}
|
|
78
78
|
${chalk.gray('$')} doc-builder build --config my-config.js ${chalk.gray('# Use custom config')}
|
|
79
79
|
`)
|
|
80
80
|
.action(async (options) => {
|
package/lib/config.js
CHANGED
|
@@ -49,12 +49,12 @@ const defaultConfig = {
|
|
|
49
49
|
};
|
|
50
50
|
|
|
51
51
|
/**
|
|
52
|
-
*
|
|
52
|
+
* Notion-inspired preset - clean, modern documentation style
|
|
53
53
|
*/
|
|
54
|
-
const
|
|
54
|
+
const notionInspiredPreset = {
|
|
55
55
|
docsDir: 'docs',
|
|
56
56
|
outputDir: 'html',
|
|
57
|
-
siteName: '
|
|
57
|
+
siteName: 'Documentation', // Clean default name
|
|
58
58
|
siteDescription: 'Transforming complex sales through intelligent automation',
|
|
59
59
|
|
|
60
60
|
features: {
|
|
@@ -67,7 +67,7 @@ const cybersolsticePreset = {
|
|
|
67
67
|
},
|
|
68
68
|
|
|
69
69
|
auth: {
|
|
70
|
-
username: '
|
|
70
|
+
username: 'admin',
|
|
71
71
|
password: 'docs2025'
|
|
72
72
|
},
|
|
73
73
|
|
|
@@ -78,7 +78,7 @@ const cybersolsticePreset = {
|
|
|
78
78
|
|
|
79
79
|
// Folder descriptions from existing code
|
|
80
80
|
folderDescriptions: {
|
|
81
|
-
'product-roadmap': 'Strategic vision, timeline, and feature planning
|
|
81
|
+
'product-roadmap': 'Strategic vision, timeline, and feature planning',
|
|
82
82
|
'product-requirements': 'Detailed product specifications, requirements documents, and feature definitions',
|
|
83
83
|
'architecture': 'System design, data flows, and technical infrastructure documentation',
|
|
84
84
|
'system-analysis': 'Comprehensive system analysis, functional requirements, and cross-component documentation',
|
|
@@ -143,8 +143,8 @@ async function loadConfig(configPath, options = {}) {
|
|
|
143
143
|
let config = { ...defaultConfig };
|
|
144
144
|
|
|
145
145
|
// Apply preset if specified
|
|
146
|
-
if (options.preset === '
|
|
147
|
-
config = { ...config, ...
|
|
146
|
+
if (options.preset === 'notion-inspired') {
|
|
147
|
+
config = { ...config, ...notionInspiredPreset };
|
|
148
148
|
}
|
|
149
149
|
|
|
150
150
|
// Load custom config file if it exists
|
|
@@ -251,7 +251,7 @@ async function createDefaultConfig() {
|
|
|
251
251
|
|
|
252
252
|
module.exports = {
|
|
253
253
|
defaultConfig,
|
|
254
|
-
|
|
254
|
+
notionInspiredPreset,
|
|
255
255
|
loadConfig,
|
|
256
256
|
createDefaultConfig
|
|
257
257
|
};
|
package/lib/core-builder.js
CHANGED
|
@@ -179,8 +179,8 @@ const folderDescriptions = {
|
|
|
179
179
|
'bubble': 'Core application platform - business logic, UI/UX, and user workflows',
|
|
180
180
|
'quickbase': 'Database schema, data management, and backend operations',
|
|
181
181
|
'activecampaign': 'Marketing automation integration and lead management system',
|
|
182
|
-
'
|
|
183
|
-
'
|
|
182
|
+
'doc-signer': 'Document signing service for digital signatures and PDF generation',
|
|
183
|
+
'api-deprecated': 'Legacy API documentation (deprecated, for reference only)',
|
|
184
184
|
'postman': 'API testing tools, collections, and test automation',
|
|
185
185
|
'mcp': 'Model Context Protocol integration and configuration',
|
|
186
186
|
'team': 'Team structure, roles, and responsibilities',
|
|
@@ -188,7 +188,7 @@ const folderDescriptions = {
|
|
|
188
188
|
'middleware': 'Integration layers and data transformation services',
|
|
189
189
|
'paths': 'User journey flows and process workflows',
|
|
190
190
|
'testing': 'Test strategies, scenarios, and quality assurance processes',
|
|
191
|
-
'
|
|
191
|
+
'api': 'API documentation and integration guides'
|
|
192
192
|
};
|
|
193
193
|
|
|
194
194
|
// Build navigation structure with rich functionality
|
|
@@ -250,8 +250,8 @@ function buildNavigationStructure(files, currentFile) {
|
|
|
250
250
|
'bubble': 'fas fa-circle',
|
|
251
251
|
'quickbase': 'fas fa-database',
|
|
252
252
|
'activecampaign': 'fas fa-envelope',
|
|
253
|
-
'
|
|
254
|
-
'
|
|
253
|
+
'doc-signer': 'fas fa-signature',
|
|
254
|
+
'api-deprecated': 'fas fa-archive',
|
|
255
255
|
'postman': 'fas fa-flask',
|
|
256
256
|
'mcp': 'fas fa-puzzle-piece',
|
|
257
257
|
'team': 'fas fa-users',
|
|
@@ -259,7 +259,7 @@ function buildNavigationStructure(files, currentFile) {
|
|
|
259
259
|
'middleware': 'fas fa-layer-group',
|
|
260
260
|
'paths': 'fas fa-route',
|
|
261
261
|
'testing': 'fas fa-vial',
|
|
262
|
-
'
|
|
262
|
+
'api': 'fas fa-plug',
|
|
263
263
|
'documentation-tool': 'fas fa-tools'
|
|
264
264
|
};
|
|
265
265
|
|
|
@@ -358,8 +358,8 @@ function buildNavigationStructure(files, currentFile) {
|
|
|
358
358
|
'bubble',
|
|
359
359
|
'quickbase',
|
|
360
360
|
'activecampaign',
|
|
361
|
-
'
|
|
362
|
-
'
|
|
361
|
+
'doc-signer',
|
|
362
|
+
'api-deprecated',
|
|
363
363
|
'postman',
|
|
364
364
|
'mcp',
|
|
365
365
|
'team',
|
|
@@ -448,6 +448,10 @@ async function buildDocumentation(config) {
|
|
|
448
448
|
const docsDir = path.join(process.cwd(), config.docsDir);
|
|
449
449
|
const outputDir = path.join(process.cwd(), config.outputDir);
|
|
450
450
|
|
|
451
|
+
// Log version for debugging
|
|
452
|
+
const packageJson = require('../package.json');
|
|
453
|
+
console.log(chalk.blue(`š¦ Using @knowcode/doc-builder v${packageJson.version}`));
|
|
454
|
+
|
|
451
455
|
// Check and create placeholder README.md if missing
|
|
452
456
|
console.log(chalk.blue('š Checking documentation structure...'));
|
|
453
457
|
const readmeGenerated = await createPlaceholderReadme(docsDir, config);
|
|
@@ -490,12 +494,28 @@ async function buildDocumentation(config) {
|
|
|
490
494
|
await createAuthPages(outputDir, config);
|
|
491
495
|
}
|
|
492
496
|
|
|
493
|
-
// Create index.html from README.html
|
|
497
|
+
// Create index.html from index.html, README.html, or generate default
|
|
494
498
|
const indexPath = path.join(outputDir, 'index.html');
|
|
499
|
+
const indexSourcePath = path.join(outputDir, 'index.html'); // from index.md
|
|
495
500
|
const readmePath = path.join(outputDir, 'README.html');
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
501
|
+
|
|
502
|
+
console.log(chalk.blue('š Checking for index.html creation...'));
|
|
503
|
+
console.log(chalk.gray(` - index.html exists: ${fs.existsSync(indexPath)})`));
|
|
504
|
+
console.log(chalk.gray(` - README.html exists: ${fs.existsSync(readmePath)})`));
|
|
505
|
+
|
|
506
|
+
if (!fs.existsSync(indexPath)) {
|
|
507
|
+
if (fs.existsSync(readmePath)) {
|
|
508
|
+
await fs.copy(readmePath, indexPath);
|
|
509
|
+
console.log(chalk.green('ā
Created index.html from README.html'));
|
|
510
|
+
} else {
|
|
511
|
+
// No README.html, create informative default page
|
|
512
|
+
console.log(chalk.yellow('ā ļø No README.html found, creating default index.html'));
|
|
513
|
+
const defaultIndex = await createDefaultIndexPage(outputDir, config, packageJson.version);
|
|
514
|
+
await fs.writeFile(indexPath, defaultIndex);
|
|
515
|
+
console.log(chalk.green('ā
Created default index.html with instructions'));
|
|
516
|
+
}
|
|
517
|
+
} else {
|
|
518
|
+
console.log(chalk.gray('ā¹ļø index.html already exists (likely from index.md)'));
|
|
499
519
|
}
|
|
500
520
|
|
|
501
521
|
console.log(chalk.green('ā
Documentation build complete!'));
|
|
@@ -504,12 +524,19 @@ async function buildDocumentation(config) {
|
|
|
504
524
|
// Create placeholder README.md if missing
|
|
505
525
|
async function createPlaceholderReadme(docsDir, config) {
|
|
506
526
|
const readmePath = path.join(docsDir, 'README.md');
|
|
527
|
+
const indexPath = path.join(docsDir, 'index.md');
|
|
507
528
|
|
|
508
|
-
// Check if README.md already exists
|
|
529
|
+
// Check if README.md or index.md already exists
|
|
509
530
|
if (fs.existsSync(readmePath)) {
|
|
531
|
+
console.log(chalk.gray(' ā README.md found'));
|
|
510
532
|
return false; // README already exists, no need to create
|
|
511
533
|
}
|
|
512
534
|
|
|
535
|
+
if (fs.existsSync(indexPath)) {
|
|
536
|
+
console.log(chalk.gray(' ā index.md found'));
|
|
537
|
+
return false; // index.md exists, no need for README
|
|
538
|
+
}
|
|
539
|
+
|
|
513
540
|
const siteName = config.siteName || 'Documentation';
|
|
514
541
|
const currentDate = new Date().toISOString().split('T')[0];
|
|
515
542
|
|
|
@@ -672,9 +699,177 @@ async function createAuthPages(outputDir, config) {
|
|
|
672
699
|
await fs.writeFile(path.join(outputDir, 'logout.html'), logoutHTML);
|
|
673
700
|
}
|
|
674
701
|
|
|
702
|
+
// Create default index page when no documentation exists
|
|
703
|
+
async function createDefaultIndexPage(outputDir, config, version) {
|
|
704
|
+
const siteName = config.siteName || 'Documentation';
|
|
705
|
+
const currentDate = new Date().toISOString();
|
|
706
|
+
|
|
707
|
+
// List all HTML files in the output directory
|
|
708
|
+
const htmlFiles = [];
|
|
709
|
+
async function findHtmlFiles(dir, baseDir = dir) {
|
|
710
|
+
const items = await fs.readdir(dir);
|
|
711
|
+
for (const item of items) {
|
|
712
|
+
const fullPath = path.join(dir, item);
|
|
713
|
+
const stat = await fs.stat(fullPath);
|
|
714
|
+
if (stat.isDirectory() && !item.startsWith('.')) {
|
|
715
|
+
await findHtmlFiles(fullPath, baseDir);
|
|
716
|
+
} else if (item.endsWith('.html') && item !== 'index.html' && item !== 'login.html' && item !== 'logout.html') {
|
|
717
|
+
const relativePath = path.relative(baseDir, fullPath);
|
|
718
|
+
htmlFiles.push(relativePath);
|
|
719
|
+
}
|
|
720
|
+
}
|
|
721
|
+
}
|
|
722
|
+
|
|
723
|
+
await findHtmlFiles(outputDir);
|
|
724
|
+
|
|
725
|
+
let fileListHtml = '';
|
|
726
|
+
if (htmlFiles.length > 0) {
|
|
727
|
+
fileListHtml = `
|
|
728
|
+
<div class="existing-files">
|
|
729
|
+
<h2>š Available Documentation</h2>
|
|
730
|
+
<p>The following documentation files were found:</p>
|
|
731
|
+
<ul>
|
|
732
|
+
${htmlFiles.map(file => `<li><a href="${file}">${file}</a></li>`).join('\n ')}
|
|
733
|
+
</ul>
|
|
734
|
+
</div>`;
|
|
735
|
+
}
|
|
736
|
+
|
|
737
|
+
return `<!DOCTYPE html>
|
|
738
|
+
<html lang="en">
|
|
739
|
+
<head>
|
|
740
|
+
<meta charset="UTF-8">
|
|
741
|
+
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
742
|
+
<title>Welcome to ${siteName}</title>
|
|
743
|
+
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
|
|
744
|
+
<link rel="stylesheet" href="/css/notion-style.css">
|
|
745
|
+
<link rel="stylesheet" href="/css/style.css">
|
|
746
|
+
<style>
|
|
747
|
+
.welcome-container {
|
|
748
|
+
max-width: 800px;
|
|
749
|
+
margin: 50px auto;
|
|
750
|
+
padding: 40px;
|
|
751
|
+
background: var(--bg-secondary);
|
|
752
|
+
border-radius: 12px;
|
|
753
|
+
box-shadow: 0 2px 8px rgba(0,0,0,0.1);
|
|
754
|
+
}
|
|
755
|
+
.welcome-container h1 {
|
|
756
|
+
color: var(--text-primary);
|
|
757
|
+
margin-bottom: 20px;
|
|
758
|
+
}
|
|
759
|
+
.welcome-container h2 {
|
|
760
|
+
color: var(--text-primary);
|
|
761
|
+
margin-top: 30px;
|
|
762
|
+
margin-bottom: 15px;
|
|
763
|
+
}
|
|
764
|
+
.welcome-container p {
|
|
765
|
+
color: var(--text-secondary);
|
|
766
|
+
line-height: 1.6;
|
|
767
|
+
margin-bottom: 15px;
|
|
768
|
+
}
|
|
769
|
+
.welcome-container pre {
|
|
770
|
+
background: var(--bg-tertiary);
|
|
771
|
+
padding: 20px;
|
|
772
|
+
border-radius: 8px;
|
|
773
|
+
overflow-x: auto;
|
|
774
|
+
margin: 20px 0;
|
|
775
|
+
}
|
|
776
|
+
.welcome-container code {
|
|
777
|
+
font-family: 'JetBrains Mono', monospace;
|
|
778
|
+
font-size: 14px;
|
|
779
|
+
}
|
|
780
|
+
.welcome-container ul {
|
|
781
|
+
margin: 20px 0;
|
|
782
|
+
padding-left: 30px;
|
|
783
|
+
}
|
|
784
|
+
.welcome-container li {
|
|
785
|
+
margin: 8px 0;
|
|
786
|
+
}
|
|
787
|
+
.version-info {
|
|
788
|
+
margin-top: 40px;
|
|
789
|
+
padding-top: 20px;
|
|
790
|
+
border-top: 1px solid var(--border-color);
|
|
791
|
+
font-size: 12px;
|
|
792
|
+
color: var(--text-tertiary);
|
|
793
|
+
}
|
|
794
|
+
.existing-files {
|
|
795
|
+
background: var(--bg-primary);
|
|
796
|
+
padding: 20px;
|
|
797
|
+
border-radius: 8px;
|
|
798
|
+
margin: 30px 0;
|
|
799
|
+
}
|
|
800
|
+
.existing-files a {
|
|
801
|
+
color: var(--link-color);
|
|
802
|
+
text-decoration: none;
|
|
803
|
+
}
|
|
804
|
+
.existing-files a:hover {
|
|
805
|
+
text-decoration: underline;
|
|
806
|
+
}
|
|
807
|
+
</style>
|
|
808
|
+
</head>
|
|
809
|
+
<body>
|
|
810
|
+
<div class="welcome-container">
|
|
811
|
+
<h1>š Welcome to ${siteName}</h1>
|
|
812
|
+
|
|
813
|
+
<p>This documentation site was generated by <strong>@knowcode/doc-builder</strong>. To add your own content, follow the instructions below.</p>
|
|
814
|
+
|
|
815
|
+
<h2>š Getting Started</h2>
|
|
816
|
+
|
|
817
|
+
<p>To create your documentation homepage, create either of these files in your <code>docs/</code> directory:</p>
|
|
818
|
+
|
|
819
|
+
<ul>
|
|
820
|
+
<li><code>index.md</code> - Primary homepage (highest priority)</li>
|
|
821
|
+
<li><code>README.md</code> - Alternative homepage</li>
|
|
822
|
+
</ul>
|
|
823
|
+
|
|
824
|
+
<h2>š Example Content</h2>
|
|
825
|
+
|
|
826
|
+
<p>Create <code>docs/index.md</code> with content like:</p>
|
|
827
|
+
|
|
828
|
+
<pre><code># Welcome to My Project
|
|
829
|
+
|
|
830
|
+
This is the homepage for my documentation.
|
|
831
|
+
|
|
832
|
+
## Features
|
|
833
|
+
|
|
834
|
+
- Feature 1
|
|
835
|
+
- Feature 2
|
|
836
|
+
- Feature 3
|
|
837
|
+
|
|
838
|
+
## Getting Started
|
|
839
|
+
|
|
840
|
+
1. Install the package
|
|
841
|
+
2. Configure your settings
|
|
842
|
+
3. Start building!</code></pre>
|
|
843
|
+
|
|
844
|
+
<h2>š§ Next Steps</h2>
|
|
845
|
+
|
|
846
|
+
<ol>
|
|
847
|
+
<li>Create <code>docs/index.md</code> or <code>docs/README.md</code></li>
|
|
848
|
+
<li>Add more markdown files for additional pages</li>
|
|
849
|
+
<li>Rebuild: <code>npx @knowcode/doc-builder build</code></li>
|
|
850
|
+
<li>Deploy: <code>npx @knowcode/doc-builder deploy</code></li>
|
|
851
|
+
</ol>
|
|
852
|
+
|
|
853
|
+
${fileListHtml}
|
|
854
|
+
|
|
855
|
+
<div class="version-info">
|
|
856
|
+
<p><strong>Debug Information:</strong></p>
|
|
857
|
+
<ul>
|
|
858
|
+
<li>doc-builder version: ${version}</li>
|
|
859
|
+
<li>Generated: ${currentDate}</li>
|
|
860
|
+
<li>Site name: ${siteName}</li>
|
|
861
|
+
<li>No index.md or README.md found in docs directory</li>
|
|
862
|
+
</ul>
|
|
863
|
+
</div>
|
|
864
|
+
</div>
|
|
865
|
+
</body>
|
|
866
|
+
</html>`;
|
|
867
|
+
}
|
|
868
|
+
|
|
675
869
|
module.exports = {
|
|
676
870
|
buildDocumentation,
|
|
677
871
|
processMarkdownContent,
|
|
678
872
|
generateHTML,
|
|
679
|
-
createPlaceholderReadme
|
|
873
|
+
createPlaceholderReadme,
|
|
874
|
+
createDefaultIndexPage
|
|
680
875
|
};
|
package/lib/deploy.js
CHANGED
|
@@ -341,23 +341,41 @@ async function deployToVercel(config, isProd = false) {
|
|
|
341
341
|
async function prepareDeployment(config) {
|
|
342
342
|
const outputDir = path.join(process.cwd(), config.outputDir || 'html');
|
|
343
343
|
|
|
344
|
+
// Log version for debugging
|
|
345
|
+
const packageJson = require('../package.json');
|
|
346
|
+
console.log(chalk.blue(`\nš¦ Preparing deployment with @knowcode/doc-builder v${packageJson.version}`));
|
|
347
|
+
|
|
344
348
|
// Create index.html from README.html if needed
|
|
345
349
|
const indexPath = path.join(outputDir, 'index.html');
|
|
350
|
+
console.log(chalk.gray(` - Checking index.html: ${fs.existsSync(indexPath) ? 'exists' : 'missing'}}`));
|
|
351
|
+
|
|
346
352
|
if (!fs.existsSync(indexPath)) {
|
|
347
353
|
const readmePath = path.join(outputDir, 'README.html');
|
|
354
|
+
console.log(chalk.gray(` - Checking README.html: ${fs.existsSync(readmePath) ? 'exists' : 'missing'}}`));
|
|
355
|
+
|
|
348
356
|
if (fs.existsSync(readmePath)) {
|
|
349
357
|
// Copy README.html to index.html for proper root page
|
|
350
358
|
fs.copyFileSync(readmePath, indexPath);
|
|
351
359
|
console.log(chalk.green('ā
Created index.html from README.html'));
|
|
352
360
|
} else {
|
|
353
|
-
// If no README.html,
|
|
354
|
-
|
|
355
|
-
|
|
361
|
+
// If no README.html, find first available HTML file or create informative page
|
|
362
|
+
console.log(chalk.yellow('ā ļø No README.html found, looking for other HTML files...'));
|
|
363
|
+
|
|
364
|
+
// Find first available HTML file
|
|
365
|
+
const htmlFiles = fs.readdirSync(outputDir)
|
|
366
|
+
.filter(file => file.endsWith('.html') && file !== 'index.html' && file !== 'login.html' && file !== 'logout.html')
|
|
367
|
+
.sort();
|
|
368
|
+
|
|
369
|
+
if (htmlFiles.length > 0) {
|
|
370
|
+
// Redirect to first HTML file
|
|
371
|
+
const firstFile = htmlFiles[0];
|
|
372
|
+
console.log(chalk.green(`ā
Creating index.html redirect to ${firstFile}`));
|
|
373
|
+
const redirectIndex = `<!DOCTYPE html>
|
|
356
374
|
<html>
|
|
357
375
|
<head>
|
|
358
376
|
<meta charset="UTF-8">
|
|
359
377
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
360
|
-
<meta http-equiv="refresh" content="0; url
|
|
378
|
+
<meta http-equiv="refresh" content="0; url=${firstFile}">
|
|
361
379
|
<title>${config.siteName || 'Documentation'}</title>
|
|
362
380
|
<link rel="stylesheet" href="/css/style.css">
|
|
363
381
|
<link rel="stylesheet" href="/css/notion-style.css">
|
|
@@ -365,15 +383,39 @@ async function prepareDeployment(config) {
|
|
|
365
383
|
<body>
|
|
366
384
|
<div style="text-align: center; margin-top: 50px; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;">
|
|
367
385
|
<h1>š ${config.siteName || 'Documentation'}</h1>
|
|
368
|
-
<p>
|
|
369
|
-
<p><a href="
|
|
386
|
+
<p>Redirecting to documentation...</p>
|
|
387
|
+
<p><a href="${firstFile}" style="color: #0366d6;">Click here if not redirected automatically</a></p>
|
|
370
388
|
</div>
|
|
371
389
|
</body>
|
|
372
390
|
</html>`;
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
391
|
+
fs.writeFileSync(indexPath, redirectIndex);
|
|
392
|
+
console.log(chalk.green(`ā
Created index.html redirect to ${firstFile}`));
|
|
393
|
+
} else {
|
|
394
|
+
// No HTML files at all - this should never happen after build
|
|
395
|
+
console.log(chalk.red('ā No HTML files found in output directory!'));
|
|
396
|
+
console.log(chalk.yellow('š This indicates a build issue. Please run: npx @knowcode/doc-builder build'));
|
|
397
|
+
|
|
398
|
+
// Create emergency fallback page
|
|
399
|
+
const { createDefaultIndexPage } = require('./core-builder');
|
|
400
|
+
const fallbackIndex = await createDefaultIndexPage(outputDir, config, packageJson.version);
|
|
401
|
+
fs.writeFileSync(indexPath, fallbackIndex);
|
|
402
|
+
console.log(chalk.green('ā
Created fallback index.html with instructions'));
|
|
403
|
+
}
|
|
376
404
|
}
|
|
405
|
+
} else {
|
|
406
|
+
console.log(chalk.gray(' ā index.html already exists'));
|
|
407
|
+
}
|
|
408
|
+
|
|
409
|
+
// Final check - log what files exist
|
|
410
|
+
console.log(chalk.blue('\nš Final deployment state:'));
|
|
411
|
+
const finalFiles = fs.readdirSync(outputDir)
|
|
412
|
+
.filter(file => file.endsWith('.html'))
|
|
413
|
+
.slice(0, 5); // Show first 5 HTML files
|
|
414
|
+
finalFiles.forEach(file => {
|
|
415
|
+
console.log(chalk.gray(` - ${file}`));
|
|
416
|
+
});
|
|
417
|
+
if (fs.readdirSync(outputDir).filter(f => f.endsWith('.html')).length > 5) {
|
|
418
|
+
console.log(chalk.gray(` - ... and ${fs.readdirSync(outputDir).filter(f => f.endsWith('.html')).length - 5} more HTML files`));
|
|
377
419
|
}
|
|
378
420
|
}
|
|
379
421
|
|
package/package.json
CHANGED
|
@@ -1,11 +1,10 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@knowcode/doc-builder",
|
|
3
|
-
"version": "1.2.
|
|
3
|
+
"version": "1.2.8",
|
|
4
4
|
"description": "Reusable documentation builder for markdown-based sites with Vercel deployment support",
|
|
5
5
|
"main": "index.js",
|
|
6
6
|
"bin": {
|
|
7
7
|
"doc-builder": "./cli.js",
|
|
8
|
-
"juno-docs": "./cli.js",
|
|
9
8
|
"@knowcode/doc-builder": "./scripts/npx-runner.js"
|
|
10
9
|
},
|
|
11
10
|
"scripts": {
|
|
@@ -17,7 +16,8 @@
|
|
|
17
16
|
"markdown",
|
|
18
17
|
"static-site-generator",
|
|
19
18
|
"vercel",
|
|
20
|
-
"
|
|
19
|
+
"notion-style",
|
|
20
|
+
"doc-builder"
|
|
21
21
|
],
|
|
22
22
|
"author": "KnowCode",
|
|
23
23
|
"license": "MIT",
|
package/scripts/setup.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Post-install setup script for @
|
|
2
|
+
* Post-install setup script for @knowcode/doc-builder
|
|
3
3
|
* This script runs after npm install to help users get started
|
|
4
4
|
*/
|
|
5
5
|
|
|
@@ -52,5 +52,5 @@ if (foundDir) {
|
|
|
52
52
|
console.log(chalk.yellow(`ā¹ļø No docs directory found. Create a 'docs' folder with markdown files to get started.\n`));
|
|
53
53
|
}
|
|
54
54
|
|
|
55
|
-
console.log(chalk.gray('For more information, visit: https://github.com/
|
|
55
|
+
console.log(chalk.gray('For more information, visit: https://github.com/knowcode/doc-builder'));
|
|
56
56
|
console.log(chalk.gray('To create a config file, run: doc-builder init --config\n'));
|