Remote GitHub CSS Demo

🔧 Troubleshooting Guide

🔧 Troubleshooting Guide

Having issues with md2html-action? This comprehensive troubleshooting guide will help you diagnose and fix common problems quickly.

🚨 Common Issues

Build Failures

Issue: Action fails to run

Symptoms:

Solutions:

  1. Check file paths in workflow:

    on:
  push:
    paths: ["docs/**/*.md"] # Make sure this matches your structure

  2. Verify branch configuration:

    on:
  push:
    branches: [main] # Ensure you're pushing to the right branch

  3. Check repository permissions:

    • Ensure Actions are enabled in repository settings
    • Verify workflow has necessary permissions

Issue: Pandoc conversion errors

Symptoms:

Solutions:

  1. Validate your Markdown:

    # Test locally with Pandoc
pandoc your-file.md -o test.html

  2. Check for unsupported syntax:

    • Remove HTML comments in Markdown
    • Fix unclosed code blocks
    • Check for invalid frontmatter

  3. Enable debug mode:

    - uses: CameronBrooks11/md2html-action@main
  with:
    pandoc-options: "--verbose"
  env:
    ACTIONS_STEP_DEBUG: true

Styling Issues

Issue: CSS not loading

Symptoms:

Solutions:

  1. Verify stylesheet name:

    # Valid options: academic, technical, blog, corporate, default, minimal
stylesheet: "technical" # Must be exact match

  2. Check custom CSS path:

    custom-css: "assets/styles.css" # File must exist in repository

  3. Test with default theme:

    stylesheet: "default" # Always works as fallback

Issue: Broken layout

Symptoms:

Solutions:

  1. Verify template compatibility:

    template: "default" # Use default template for troubleshooting

  2. Check Markdown structure:

    # Main Title (required for proper structure)

## Section Headers (for TOC generation)

Content here...

  3. Clear browser cache:

    • Hard refresh (Ctrl+F5)
    • Clear cache and cookies
    • Test in incognito mode

Content Issues

Issue: Table of contents not generating

Symptoms:

Solutions:

  1. Enable TOC in Pandoc options:

    pandoc-options: "--toc --toc-depth=3"

  2. Use proper Markdown headers:

    # Level 1 Header

## Level 2 Header

### Level 3 Header

  3. Avoid HTML in headers:

    # Good Header

# <span>Bad Header</span> # Don't do this

Issue: Math not rendering

Symptoms:

Solutions:

  1. Enable math support:

    pandoc-options: "--katex" # or --mathjax

  2. Use proper LaTeX syntax:

    Inline: $E = mc^2$

Block:

$$
\int_{-\infty}^{\infty} e^{-x^2} dx = \sqrt{\pi}
$$

  3. Escape special characters:

    # In Markdown, escape backslashes

$$\\alpha + \\beta = \\gamma$$

Symptoms:

Solutions:

  1. Use relative paths:

    [Good](../other-page.md)
[Bad](/absolute/path.md)

  2. Link to HTML files in output:

    # During development, link to .md

[Development](other-page.md)

# In production, Pandoc converts to .html

[Production](other-page.html)

  3. Check file existence:

    # Verify files exist in your repository
find docs -name "*.md" -type f

Image Issues

Issue: Images not displaying

Symptoms:

Solutions:

  1. Use relative paths:

    ![Good](media/image.jpg)
![Bad](/absolute/path/image.jpg)

  2. Verify image files exist:

    ls -la docs/media/

  3. Check image formats:

    # Supported formats

![JPG](image.jpg)
![PNG](image.png)
![GIF](image.gif)
![WebP](image.webp)

  4. Add images to repository:

    git add docs/media/
git commit -m "Add images"
git push

🐛 Debugging Techniques

Enable Verbose Logging

- name: Debug conversion
  uses: CameronBrooks11/md2html-action@main
  with:
    source-dir: "docs"
    pandoc-options: "--verbose"
  env:
    ACTIONS_STEP_DEBUG: true
    RUNNER_DEBUG: 1

Test Locally

  1. Install Pandoc:

    # macOS
brew install pandoc

# Ubuntu/Debian
sudo apt-get install pandoc

# Windows
choco install pandoc

  2. Test conversion:

    pandoc docs/index.md -o test.html --standalone --toc

  3. Test with specific template:

    pandoc docs/index.md \
  --template=templates/default.html \
  --css=stylesheets/technical.css \
  --toc \
  --standalone \
  -o test.html

Validate Content

  1. Check Markdown syntax:

    # Install markdownlint
npm install -g markdownlint-cli

# Validate files
markdownlint docs/**/*.md

  2. Validate HTML output:

    # Install html5validator
pip install html5validator

# Validate generated HTML
html5validator --root output/

  3. Check links:

    # Install markdown-link-check
npm install -g markdown-link-check

# Check all markdown files
find docs -name "*.md" -exec markdown-link-check {} \;

🔍 Performance Issues

Slow Build Times

Symptoms:

Solutions:

  1. Limit file processing:

    on:
  push:
    paths: ["docs/**/*.md"] # Only trigger on doc changes

  2. Use caching:

    - name: Cache Pandoc
  uses: actions/cache@v3
  with:
    path: ~/.cache/pandoc
    key: ${{ runner.os }}-pandoc-${{ hashFiles('docs/**/*.md') }}

  3. Optimize images:

    # Compress images before committing
find docs -name "*.jpg" -exec jpegoptim --max=85 {} \;
find docs -name "*.png" -exec optipng -o2 {} \;

Large Output Size

Solutions:

  1. Minimize CSS:

    - name: Minify CSS
  run: |
    npm install -g clean-css-cli
    find output -name "*.css" -exec cleancss -o {} {} \;

  2. Compress HTML:

    - name: Compress HTML
  run: |
    npm install -g html-minifier
    find output -name "*.html" -exec html-minifier --minify-css --minify-js -o {} {} \;

🛠️ Workflow Debugging

Check Action Logs

  1. Go to Actions tab in your GitHub repository
  2. Click on the failed workflow run
  3. Expand the md2html-action step to see detailed logs
  4. Look for error messages in red text

Common Log Messages

# File not found
Error: ENOENT: no such file or directory, open 'docs/missing.md'
Solution: Check file paths and ensure files exist

# Permission denied
Error: EACCES: permission denied
Solution: Check repository permissions and workflow settings

# Pandoc error
pandoc: Error reading docs/file.md
Solution: Check Markdown syntax and encoding

# Template error
pandoc: template error: variable title has no value
Solution: Add title to frontmatter or use default template

Manual Testing

name: Debug Workflow

on:
  workflow_dispatch: # Manual trigger

jobs:
  debug:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: List files
        run: |
          echo "Repository contents:"
          find . -type f -name "*.md" | head -20

      - name: Check Pandoc
        run: |
          pandoc --version
          pandoc --list-templates

      - name: Test conversion
        run: |
          if [ -f "docs/index.md" ]; then
            pandoc docs/index.md -o test.html --standalone
            echo "✅ Basic conversion successful"
          else
            echo "❌ docs/index.md not found"
          fi

      - name: Test with action
        uses: CameronBrooks11/md2html-action@main
        with:
          source-dir: "docs"
          output-dir: "debug-output"
          stylesheet: "default"

📱 Mobile and Browser Issues

Mobile Display Problems

Solutions:

  1. Test responsive design:

    <!-- Add to custom template -->
<meta name="viewport" content="width=device-width, initial-scale=1.0" />

  2. Check mobile-specific CSS:

    @media (max-width: 768px) {
  .table-of-contents {
    width: 100%;
    float: none;
  }
}

Browser Compatibility

  1. Test in multiple browsers:

    • Chrome (latest)
    • Firefox (latest)
    • Safari (latest)
    • Edge (latest)

  2. Check for CSS features:

    /* Provide fallbacks for modern CSS */
.gradient-text {
  color: #333; /* fallback */
  background: linear-gradient(45deg, #333, #666);
  -webkit-background-clip: text;
  background-clip: text;
}

🆘 Getting Help

Before Asking for Help

  1. Check this troubleshooting guide thoroughly
  2. Search existing issues on GitHub
  3. Test with minimal configuration (default theme, simple Markdown)
  4. Gather relevant information:
    • Workflow file content
    • Error messages from logs
    • Sample Markdown files
    • Expected vs actual output

Where to Get Help

  1. GitHub Issues:

    • Report bugs
    • Request features
    • Get technical support

  2. GitHub Discussions:

    • Ask questions
    • Share configurations
    • Community support

  3. Documentation:

Creating a Good Issue Report

## Bug Report

**Describe the bug:**
Clear description of what's wrong

**To Reproduce:**

1. Step 1
2. Step 2
3. Error occurs

**Expected behavior:**
What should happen

**Workflow configuration:**

```yaml
# Your workflow file content
```

Error logs:

# Paste error messages here

Environment:

Additional context: Any other relevant information


## 🎯 Prevention Tips

### Best Practices

1. **Start simple:**
   - Use default theme initially
   - Test with basic Markdown
   - Add complexity gradually

2. **Version control everything:**
   - Commit templates and CSS
   - Track workflow changes
   - Use meaningful commit messages

3. **Test before deploying:**
   - Use pull request workflows
   - Test in staging environment
   - Validate output manually

4. **Monitor and maintain:**
   - Check build status regularly
   - Update dependencies
   - Review and update documentation

### Automation

```yaml
# Add automated checks
- name: Validate Markdown
  run: markdownlint docs/**/*.md

- name: Check links
  run: markdown-link-check docs/**/*.md

- name: Validate HTML
  run: html5validator output/**/*.html

📞 Quick Reference

Problem Quick Fix
Action not running Check file paths in workflow triggers
No styling Verify stylesheet name spelling
TOC missing Add --toc to pandoc-options
Math not rendering Add --katex to pandoc-options
Images broken Use relative paths, check file existence
Links broken Use relative paths, link to .html files
Build timeout Optimize images, use caching
HTML invalid Check Markdown syntax, use validators

Still having trouble? Don’t hesitate to open an issue or start a discussion!