Project Local Configuration

A comprehensive guide to setting up HBStack project configuration including EditorConfig, linting, and markdown handling for code quality and consistency.

Project Configuration for Formatting and Linting

This project implements a comprehensive approach to code formatting, linting, and markdown handling. Below is a detailed explanation of how these components work together to maintain code quality and consistency.

EditorConfig (.editorconfig)

The .editorconfig file provides basic code style definitions that work across different editors and IDEs.

 1[*]
 2end_of_line = lf            # Use Unix-style line endings
 3insert_final_newline = true # Ensure files end with a newline
 4charset = utf-8             # Set UTF-8 character encoding
 5trim_trailing_whitespace = true # Remove trailing whitespace
 6indent_style = space        # Use spaces for indentation
 7indent_size = 2             # Use 2 spaces per indentation level
 8
 9[*.{md,markdown}]
10trim_trailing_whitespace = false # Don't trim trailing whitespace in markdown
11                                 # (preserves intentional line breaks)

Key points about EditorConfig:

• It provides baseline formatting rules that any editor supporting EditorConfig will follow
• It handles basic concerns like line endings, indentation, and encoding
• The trim_trailing_whitespace = false for markdown files is crucial for preserving intended line breaks (two spaces at the end of a line)

Prettier Configuration (.prettierrc)

Prettier handles more sophisticated code formatting with the .prettierrc file.

 1{
 2  "singleQuote": true,
 3  "tabWidth": 2,
 4  "useTabs": false,
 5  "trailingComma": "es5",
 6  "printWidth": 100,
 7  "endOfLine": "lf",
 8  "overrides": [
 9    {
10      "files": "*.md",
11      "options": {
12        "proseWrap": "preserve",
13        "printWidth": 100,
14        "parser": "markdown"
15      }
16    }
17  ]
18}

Important Prettier aspects:

• Prettier automatically formats code when files are saved (when configured with VS Code)
• For markdown, Prettier fixes issues like:
  • Basic indentation
  • Trailing whitespace (MD009)
  • Consistent heading formats
• However, Prettier doesn’t handle some markdown-specific rules like:
  • Blank lines around code blocks (MD031)
  • Specialized markdown structures
  • It uses its own parser, look for parser: "markdown" in the overrides section
• The proseWrap: "preserve" option is crucial for markdown to maintain line breaks and formatting
• The printWidth option sets the maximum line length for code formatting
• The plugins section includes the prettier-plugin-go-template for handling Go templates in markdown files
• The overrides section allows for specific configurations for different file types, in this case, markdown files
• The parser option specifies the parser to use for markdown files, ensuring proper formatting
• The endOfLine option ensures consistent line endings across different operating systems
• The trailingComma option specifies how trailing commas are handled in objects and arrays

VS Code Integration

VS Code settings help connect these tools together:

Settings in .vscode/settings.json

1{
2  "editor.formatOnSave": true,
3  "editor.defaultFormatter": "esbenp.prettier-vscode",
4  "[markdown]": {
5    "editor.defaultFormatter": "esbenp.prettier-vscode"
6  }
7}

Prettier-specific settings in .vscode/prettier.json

1{
2  "prettier.configPath": ".prettierrc",
3  "prettier.requireConfig": true,
4  "prettier.useEditorConfig": true,
5  "prettier.documentSelectors": ["**/*.{html,hugo}"]
6}

Why separate Prettier settings in VS Code:

• The .vscode/prettier.json contains settings specific to the Prettier VS Code extension
• This separation helps maintain clean configuration files and prevents settings conflicts
• It allows more granular control over how Prettier runs within VS Code specifically

Formatting and Linting Behavior

When working with Markdown files in this project:

1. On Save Behavior:

   • Prettier automatically runs and fixes basic formatting issues
   • Simple issues like trailing whitespace (MD009) are fixed
   • More complex markdown-specific issues (like MD031) are not automatically fixed

2. Manual Formatting:

   • For markdown-specific rules like MD031 (blank lines around code blocks), manual formatting is required
   • This can be done using “Format Document With” → “markdownlint” in VS Code

3. Linting vs. Formatting:

   • Linting (showing warnings) comes from markdownlint
   • Formatting (fixing issues) comes primarily from Prettier
   • They complement each other but serve different purposes

Common Markdown Linting Rules

Best Practices for This Project

1. Use VS Code with the recommended extensions
2. Let Prettier handle basic formatting on save
3. For markdown-specific issues, manually format with markdownlint as needed
4. When adding new markdown files, ensure you follow the proper structure including frontmatter

Recent Configuration Updates

Update: July 9, 2025 - VS Code Settings Cleanup and Optimization

Issue: Multiple conflicting configuration files were causing VS Code file saving problems and performance issues. The workspace had redundant and conflicting settings across various configuration files that were interfering with proper file operations.

Changes Made:

1. Prettier Configuration Cleanup

Removed: .prettierrc file (conflicting configuration) Kept: .prettierrc.json as the single source of truth

Updated .prettierrc.json:

 1{
 2  "singleQuote": true,
 3  "tabWidth": 2,
 4  "useTabs": false,
 5  "trailingComma": "es5",
 6  "printWidth": 100,
 7  "endOfLine": "lf",
 8  "overrides": [
 9    {
10      "files": "*.md",
11      "options": {
12        "proseWrap": "preserve",
13        "printWidth": 100,
14        "parser": "markdown"
15      }
16    }
17  ]
18}

Reason: Removed problematic plugins (prettier-plugin-go-template and prettier-plugin-md-nocjsp) that were causing formatting conflicts and VS Code performance issues.

2. VS Code Settings Optimization

Updated .vscode/settings.json:

 1{
 2  "editor.formatOnSave": true,
 3  "editor.defaultFormatter": "esbenp.prettier-vscode",
 4  "editor.codeActionsOnSave": {
 5    "source.fixAll": "explicit"
 6  },
 7  "[markdown]": {
 8    "editor.defaultFormatter": "esbenp.prettier-vscode",
 9    "editor.wordWrap": "on"
10  },
11  "[yaml]": {
12    "editor.defaultFormatter": "esbenp.prettier-vscode"
13  },
14  "[json]": {
15    "editor.defaultFormatter": "esbenp.prettier-vscode"
16  }
17}

Reason: Simplified and unified formatter settings, removed redundant configurations that were causing conflicts.

3. Workspace Configuration Cleanup

Updated hugo-with-docker.code-workspace:

• Removed duplicate and conflicting editor settings
• Streamlined Prettier configuration
• Removed problematic plugin references
• Kept only essential workspace-specific settings

Reason: Eliminated conflicts between workspace-level and folder-level settings that were causing inconsistent behavior.

4. Package.json Updates

Removed Dependencies:

• prettier-plugin-go-template: Was causing formatting conflicts
• prettier-plugin-md-nocjsp: Was interfering with markdown processing

Added Debug Scripts:

 1{
 2  "scripts": {
 3    "debug": "hugo server --debug --verbose --logLevel debug",
 4    "debug:build": "hugo --debug --verbose --logLevel debug --minify",
 5    "diagnose": "echo '=== Hugo Diagnostics ===' && hugo version && hugo env && hugo config",
 6    "troubleshoot": "npm run diagnose && npm run check:modules && npm run check:build",
 7    "check:links": "hugo server --navigateToChanged=false --disableFastRender --logLevel info 2>&1 | grep -i 'error\\|warn' || echo 'No link errors found'",
 8    "check:config": "hugo config --logLevel info",
 9    "check:modules": "hugo mod verify && hugo mod graph",
10    "check:build": "hugo --dry-run --logLevel info",
11    "health": "hugo version && hugo mod verify && hugo config | head -20"
12  }
13}

Reason: Added comprehensive debugging and troubleshooting capabilities to help diagnose project issues quickly.

Impact of Changes

Problems Resolved:

• ✅ VS Code file saving issues eliminated
• ✅ Improved editor performance and responsiveness
• ✅ Consistent formatting behavior across the project
• ✅ Eliminated conflicting configuration sources
• ✅ Added robust debugging capabilities

Benefits:

• Unified configuration approach reduces maintenance overhead
• Faster file operations and editor responsiveness
• Clear troubleshooting path for future issues
• Consistent development experience across team members
• Improved project maintainability

Migration Notes:

• If you were relying on Go template formatting, you may need to format those files manually
• The new debug scripts provide comprehensive project health monitoring
• All changes are backward compatible with existing Hugo functionality

FAQ