🔧 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:

Workflow doesn’t trigger
Action step shows “skipped”
No HTML output generated

Solutions:

Check file paths in workflow:

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

Verify branch configuration:

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

Check repository permissions:
- Ensure Actions are enabled in repository settings
- Verify workflow has necessary permissions

Issue: Pandoc conversion errors

Symptoms:

Action runs but fails during conversion
Error messages about invalid Markdown
HTML files not generated

Solutions:

Validate your Markdown:

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

Check for unsupported syntax:
- Remove HTML comments in Markdown
- Fix unclosed code blocks
- Check for invalid frontmatter

Enable debug mode:

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

Styling Issues

Issue: CSS not loading

Symptoms:

HTML generated but no styling
Default browser styles only
Theme not applied

Solutions:

Verify stylesheet name:

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

Check custom CSS path:

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

Test with default theme:

stylesheet: "default" # Always works as fallback

Issue: Broken layout

Symptoms:

Content overlapping
Missing navigation
Table of contents not showing

Solutions:

Verify template compatibility:

template: "default" # Use default template for troubleshooting

Check Markdown structure:

# Main Title (required for proper structure)

## Section Headers (for TOC generation)

Content here...

Clear browser cache:
- Hard refresh (Ctrl+F5)
- Clear cache and cookies
- Test in incognito mode

Content Issues

Issue: Table of contents not generating

Symptoms:

TOC section empty
No navigation links
Headers not linked

Solutions:

Enable TOC in Pandoc options:
```
pandoc-options: "--toc --toc-depth=3"
```

Use proper Markdown headers:

# Level 1 Header

## Level 2 Header

### Level 3 Header

Avoid HTML in headers:

# Good Header

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

Issue: Math not rendering

Symptoms:

LaTeX code showing as plain text
Math formulas not formatted
Equations display incorrectly

Solutions:

Enable math support:

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

Use proper LaTeX syntax:

Inline: $E = mc^2$

Block:

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

Escape special characters:

# In Markdown, escape backslashes

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

Issue: Links not working

Symptoms:

404 errors on internal links
External links broken
Navigation doesn’t work

Solutions:

Use relative paths:

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

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)

Check file existence:

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

Image Issues

Issue: Images not displaying

Symptoms:

Broken image icons
Alt text showing instead of images
404 errors for image files

Solutions:

Use relative paths:

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

Verify image files exist:
```
ls -la docs/media/
```

Check image formats:

# Supported formats

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

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

Install Pandoc:

# macOS
brew install pandoc

# Ubuntu/Debian
sudo apt-get install pandoc

# Windows
choco install pandoc

Test conversion:

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

Test with specific template:

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

Validate Content

Check Markdown syntax:

# Install markdownlint
npm install -g markdownlint-cli

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

Validate HTML output:

# Install html5validator
pip install html5validator

# Validate generated HTML
html5validator --root output/

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:

Workflow takes too long
Action times out
Build queue backs up

Solutions:

Limit file processing:

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

Use caching:

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

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:

Minimize CSS:

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

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

Go to Actions tab in your GitHub repository
Click on the failed workflow run
Expand the md2html-action step to see detailed logs
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:

Test responsive design:

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

Check mobile-specific CSS:

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

Browser Compatibility

Test in multiple browsers:
- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

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

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

Where to Get Help

GitHub Issues:
- Report bugs
- Request features
- Get technical support
GitHub Discussions:
- Ask questions
- Share configurations
- Community support
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:

OS: [e.g., Ubuntu 20.04]
Pandoc version: [if known]
Repository: [link if public]

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!