@knowcode/doc-builder 1.3.1 → 1.3.2

package/CHANGELOG.md

@@ -5,6 +5,37 @@ All notable changes to @knowcode/doc-builder will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.2] - 2025-07-19
+
+### Added
+- New `claude-hints` command to generate Claude.md documentation standards
+- Comprehensive guide for Claude AI to produce consistent markdown documentation
+- Support for both markdown and plain text output formats
+- Option to save hints directly to a file
+
+### Fixed
+- Further reduced top spacing to exactly 40px from the horizontal bar
+- Adjusted header height from 50px to 40px
+- Removed breadcrumb height entirely (0px) for minimal spacing
+- Set content top padding to fixed 40px for precise control
+
+### Features
+- Document structure standards with metadata requirements
+- Naming conventions for different document types
+- Mermaid diagram best practices
+- Information verification standards (✅/❓)
+- File organization patterns
+- Git commit practices
+- Markdown formatting guidelines
+- Security and maintenance considerations
+
+### Usage
+```bash
+doc-builder claude-hints                  # Display to console
+doc-builder claude-hints -o CLAUDE.md     # Save to file
+doc-builder claude-hints --format text    # Plain text format
+```
+
 ## [1.3.1] - 2025-07-19
 
 ### Fixed

package/assets/css/notion-style.css

@@ -125,8 +125,8 @@
   /* Layout */
   --container-padding-mobile: 20px;
   --container-padding-desktop: 40px;
-  --header-height: 50px;
-  --breadcrumb-height: 30px;
+  --header-height: 40px;
+  --breadcrumb-height: 0px;
   --sidebar-width: 280px;
 }
 
@@ -705,7 +705,7 @@ pre code {
 
 .content {
   flex: 1;
-  padding: var(--space-6) var(--space-8);
+  padding: 40px var(--space-8);
   overflow-y: auto;
   background: var(--color-bg-default);
 }

package/assets/css/style.css

@@ -44,8 +44,8 @@
   /* Layout */
   --sidebar-width: 280px;
   --content-max-width: 65rem;
-  --header-height: 50px;
-  --breadcrumb-height: 30px;
+  --header-height: 40px;
+  --breadcrumb-height: 0px;
   --banner-offset: 0rem;
   
   /* Transitions */
@@ -1087,7 +1087,7 @@ em, i {
 .content {
   flex: 1;
   margin-left: var(--sidebar-width);
-  padding: var(--space-lg) var(--space-2xl) var(--space-xl);
+  padding: 40px var(--space-2xl) var(--space-xl);
   max-width: calc(var(--content-max-width) + var(--space-2xl) * 2);
   transition: margin-left var(--transition-base);
 }

package/cli.js

@@ -471,6 +471,289 @@ ${chalk.yellow('What gets created:')}
     }
   });
 
+// Claude hints command
+program
+  .command('claude-hints')
+  .description('Generate Claude.md hints for documentation standards')
+  .option('-o, --output <path>', 'output file path (default: stdout)')
+  .option('--format <format>', 'output format: md or text (default: md)')
+  .addHelpText('after', `
+${chalk.yellow('What this does:')}
+  Generates a comprehensive guide for Claude.md configuration
+  that helps Claude produce well-structured markdown documentation
+  following best practices and consistent standards.
+
+${chalk.yellow('Usage:')}
+  ${chalk.gray('$')} doc-builder claude-hints                  ${chalk.gray('# Display to console')}
+  ${chalk.gray('$')} doc-builder claude-hints -o CLAUDE.md     ${chalk.gray('# Save to file')}
+  ${chalk.gray('$')} doc-builder claude-hints --format text    ${chalk.gray('# Plain text format')}
+
+${chalk.yellow('What gets included:')}
+  • Document structure standards
+  • Naming conventions for different doc types
+  • Mermaid diagram best practices
+  • Information verification standards (✅/❓)
+  • File organization patterns
+  • Git commit practices
+  • Markdown formatting guidelines
+`)
+  .action((options) => {
+    const claudeHints = `# Documentation Standards for Claude.md
+
+Add these instructions to your CLAUDE.md file to ensure consistent, high-quality documentation generation.
+
+## Document Standards and Conventions
+
+### Document Structure
+
+**Document Title Format**
+- Use \`# Document Title\`
+- Include metadata:
+  - **Generated**: YYYY-MM-DD HH:MM UTC
+  - **Status**: Draft/In Progress/Complete
+  - **Verified**: ✅ (for verified information) / ❓ (for speculated information)
+
+### Overview Section
+- Provide a brief description of the document's contents
+- Clearly explain the purpose and scope
+
+## Content Sections
+### Subsection
+Content with clear headings and logical flow.
+
+## Document History
+| Date | Author | Changes |
+|------|--------|---------|
+| YYYY-MM-DD | Name | Initial creation |
+| YYYY-MM-DD | Name | Updated section X |
+
+### Naming Conventions
+
+- Analysis documents: analysis-{topic}-{specifics}.md
+- Design documents: design-{component}-{feature}.md
+- Implementation plans: plan-{feature}-implementation.md
+- Technical guides: {component}-{topic}-guide.md
+- Overview documents: {system}-overview.md
+- Testing documents: test-{component}-{type}.md
+- Troubleshooting guides: troubleshoot-{issue}-guide.md
+- API documentation: api-{service}-reference.md
+
+## Content Standards
+
+### 1. Mermaid Diagrams
+- Include diagrams wherever they help explain complex concepts
+- Use consistent node naming and styling
+- Add clear labels and descriptions
+- Example:
+\`\`\`mermaid
+graph TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Process]
+    B -->|No| D[End]
+    
+    style A fill:#f9f,stroke:#333,stroke-width:2px
+    style B fill:#bbf,stroke:#333,stroke-width:2px
+\`\`\`
+
+### 2. Information Verification
+- Mark all information as either verified (✅) or speculated (❓)
+- Include sources for verified information
+- Clearly indicate assumptions
+- Example:
+  - ✅ **Verified**: Based on official documentation
+  - ❓ **Speculated**: Assumed based on common patterns
+
+### 3. Code Examples
+- Use proper syntax highlighting
+- Include context and explanations
+- Show both correct and incorrect usage where applicable
+- Add comments explaining key concepts
+
+### 4. File Organization
+- Active files in appropriate directories
+- Unused files moved to archive/ with descriptive names
+- Temporary files include "temp" in filename
+- Create docs/ directory structure:
+  \`\`\`
+  docs/
+  ├── architecture/
+  ├── api/
+  ├── guides/
+  ├── troubleshooting/
+  └── README.md
+  \`\`\`
+
+### 5. Version Control
+- Commit after material changes or milestones
+- Use descriptive commit messages
+- Group related changes
+- Example commit messages:
+  - "Add API authentication guide"
+  - "Update deployment architecture diagram"
+  - "Fix broken links in troubleshooting guide"
+
+## Markdown Best Practices
+
+### Headers
+- Use hierarchical structure (H1 for title, H2 for main sections)
+- Don't skip header levels
+- Keep headers concise but descriptive
+
+### Lists
+- Use bullet points for unordered lists
+- Use numbers for sequential steps
+- Indent nested lists properly
+
+### Tables
+- Include headers and alignment
+- Keep tables readable in raw markdown
+- Example:
+  \`\`\`markdown
+  | Feature | Status | Notes |
+  |---------|--------|-------|
+  | Auth    | ✅ Done | Uses JWT |
+  | API     | 🚧 WIP  | In progress |
+  \`\`\`
+
+### Links
+- Use descriptive link text, not "click here"
+- Prefer relative links for internal docs
+- Check links regularly for validity
+
+### Images
+- Include alt text and captions
+- Store images in docs/assets/ or docs/images/
+- Use descriptive filenames
+
+## Documentation Requirements
+
+### Timestamp
+- Always include generation date at top
+- Format: **Generated**: YYYY-MM-DD HH:MM UTC
+
+### Status Tracking
+- Mark document status (Draft/Complete)
+- Include last review date
+- Note planned updates
+
+### Cross-references
+- Link to related documents
+- Create index/navigation pages
+- Maintain a documentation map
+
+### Examples
+- Include practical examples
+- Show real-world use cases
+- Provide sample configurations
+
+### Troubleshooting
+- Add common issues and solutions
+- Include error messages verbatim
+- Provide step-by-step resolution
+
+## Quality Standards
+
+### Clarity
+- Write for your audience's technical level
+- Define acronyms on first use
+- Avoid jargon without explanation
+
+### Completeness
+- Cover all aspects of the topic
+- Include edge cases
+- Document limitations
+
+### Accuracy
+- Verify technical details
+- Test code examples
+- Update when systems change
+
+### Consistency
+- Use same terminology throughout
+- Follow established patterns
+- Maintain style guide compliance
+
+### Maintenance
+- Review quarterly
+- Update version numbers
+- Archive outdated content
+
+## Special Considerations
+
+### Security
+- Never include credentials or sensitive data
+- Use placeholders for secrets
+- Document security implications
+
+### Performance
+- Document performance implications
+- Include benchmarks where relevant
+- Note resource requirements
+
+### Dependencies
+- List all dependencies and versions
+- Note compatibility requirements
+- Document upgrade paths
+
+### Compatibility
+- Note platform/version requirements
+- Document breaking changes
+- Provide migration guides
+
+### Accessibility
+- Use clear language and structure
+- Provide text alternatives
+- Consider screen reader users
+
+## Additional Claude.md Instructions
+
+### When Creating Documentation
+- Always put md documents in the docs/ directory
+- Use mermaid diagrams whenever it makes sense to explain something
+- Explain things diagrammatically when possible
+- Create any new md docs into the docs directory and put in a relevant folder
+
+### Git Practices
+- Do a git commit after material changes or milestone
+- After any material changes or a milestone commit the changes to git
+- As files become unused - move them to archive and rename
+
+### Testing and Temporary Files
+- When creating temporary temp files for testing - put "temp" in the file name
+- Create temp files with descriptive names like "temp-test-api-response.json"
+
+### Documentation Maintenance
+- Regularly remove outdated mermaid diagram files (.md) from docs/ directory
+- When diagram generation scripts are run, they should REPLACE existing MD files
+- Use clean, consistent naming without version suffixes
+
+This comprehensive guide ensures consistent, high-quality documentation that is easy to maintain and navigate.`;
+
+    // Output the hints
+    if (options.output) {
+      try {
+        fs.writeFileSync(options.output, claudeHints);
+        console.log(chalk.green(`✅ Claude hints saved to ${options.output}`));
+      } catch (error) {
+        console.error(chalk.red(`Error writing file: ${error.message}`));
+        process.exit(1);
+      }
+    } else {
+      // Output to console
+      if (options.format === 'text') {
+        // Strip markdown formatting for plain text
+        const plainText = claudeHints
+          .replace(/#{1,6}\s/g, '')
+          .replace(/\*\*/g, '')
+          .replace(/`([^`]+)`/g, '$1')
+          .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1');
+        console.log(plainText);
+      } else {
+        console.log(claudeHints);
+      }
+    }
+  });
+
 // Parse arguments
 program.parse(process.argv);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@knowcode/doc-builder",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "Reusable documentation builder for markdown-based sites with Vercel deployment support",
   "main": "index.js",
   "bin": {