Wiki: building Jekyll sites - MonikaBarget/distant-reading GitHub Wiki

### VitePress: Missing Top Bar and Wide Text CSS or config conflicts caused the top bar to disappear in VitePress, showing a hamburger menu and overly wide text blocks that reduced readability across standard desktop views.
### VitePress: Syntax Error in config.mts A stray comma or brace in `config.mts` led to a build-breaking syntax error. Site features failed entirely until the file was cleaned and corrected.
### VitePress: Unsupported layout Property Specifying a `layout` key in `themeConfig` breaks VitePress builds. Layouts must follow internal structure — manual layout injection is not supported and causes rendering errors.
### VitePress: Inconsistent Rendering Across Browsers VitePress layout looked correct in Chrome but defaulted to mobile view in Firefox. Browser CSS differences required full cross-browser debugging and layout validation.
### Check Braces and Brackets Mismatched or missing brackets and braces in `config.mts` lead to build failures. Carefully check all `[ ... ]` and `{ ... }` blocks for closure and alignment.
### Use Linting Tools Run `tsc config.mts` or `eslint` to catch syntax errors like stray commas or wrong array structures. These tools identify errors before the build process fails.
### Validate TypeScript Syntax Ensure `.mts` files follow strict TypeScript rules. Incorrectly typed objects or invalid structure will block VitePress builds. Follow `.ts` standards throughout the config file.
### Inspect Entire File Manually check for bracket and comma placement throughout `config.mts`. Most build errors arise near trailing commas or half-closed blocks flagged by your editor or compiler.
### Rebuild and Verify After fixes, run `npm run build` again to check if the site compiles. Share config snippets for help if errors persist after syntax corrections.
### VitePress: Double Sidebar Issue Duplicate sidebars appeared due to overlapping config entries or CSS imports. One sidebar was empty, the other functional — both required cleanup for clarity.
### VitePress: Custom CSS Placement To apply global CSS changes, use `override.css` inside `.vitepress/theme` and import it via `index.js`. Without this, custom styles won’t load consistently.
### Markdown: Link to Full Image View Wrap Markdown images in `` tags to allow full-sized views. Markdown doesn’t support opening in a new tab natively, so HTML or plugin fallback is needed.
### Markdown: Cross-Platform Link Behavior Different Markdown renderers treat links differently — some open in the same tab, others in a new one. Plugins or HTML are required for consistent cross-platform behavior.
### Markdown: Alt Text and Accessibility Alt text improves accessibility for screen readers. Markdown lacks a `target="_blank"` attribute, so link higher-res versions directly for clarity and usability.
### Broken Link Checker: Quick Setup Install with `npm install -g broken-link-checker` and run `blc https://yourusername.github.io/your-repo/ -ro` to check for broken external and internal links.
### Linkinator: Alternative Link Checker Install Linkinator using `npm install -g linkinator`, then run it on your GitHub Pages URL to quickly scan for broken links across Markdown or HTML content.
### Automating Link Checks in package.json Add `"check-links": "blc https://yourusername.github.io/your-repo/ -ro"` to your `package.json` scripts and run with `npm run check-links` for routine checks. Example: 
  // package.json
  {
    "scripts": {
      "check-links": "blc https://yourusername.github.io/your-repo/ -ro"
    }
  }
  // Run with:
  npm run check-links
### CI/CD Integration for Link Checks Automate broken link detection via GitHub Actions. Add a step in your workflow YAML to run `npm run check-links` during the build process: 
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
       - name: Check links
         run: npm run check-links
⚠️ **GitHub.com Fallback** ⚠️