455 lines
12 KiB
Markdown
455 lines
12 KiB
Markdown
# Troubleshooting Guide
|
||
|
||
This guide covers common issues and their solutions. For more information, see [FAQ.md](FAQ.md) or check [GitHub Discussions](https://github.com/alshedivat/al-folio/discussions).
|
||
|
||
<!--ts-->
|
||
|
||
- [Troubleshooting Guide](#troubleshooting-guide)
|
||
- [Deployment Issues](#deployment-issues)
|
||
- [Site fails to deploy on GitHub Pages](#site-fails-to-deploy-on-github-pages)
|
||
- [Custom domain becomes blank after deployment](#custom-domain-becomes-blank-after-deployment)
|
||
- [GitHub Actions: "Unknown tag 'toc'" error](#github-actions-unknown-tag-toc-error)
|
||
- [Local Build Issues](#local-build-issues)
|
||
- [Docker build fails](#docker-build-fails)
|
||
- [Ruby dependency issues](#ruby-dependency-issues)
|
||
- [Port already in use](#port-already-in-use)
|
||
- [Styling & Layout Problems](#styling--layout-problems)
|
||
- [CSS and JS not loading properly](#css-and-js-not-loading-properly)
|
||
- [Site looks broken after deployment](#site-looks-broken-after-deployment)
|
||
- [Theme colors not applying](#theme-colors-not-applying)
|
||
- [Content Not Appearing](#content-not-appearing)
|
||
- [Blog posts not showing up](#blog-posts-not-showing-up)
|
||
- [Publications not displaying](#publications-not-displaying)
|
||
- [Images not loading](#images-not-loading)
|
||
- [Configuration Issues](#configuration-issues)
|
||
- [YAML syntax errors](#yaml-syntax-errors)
|
||
- [Feed (RSS/Atom) not working](#feed-rssatom-not-working)
|
||
- [Search not working](#search-not-working)
|
||
- [Feature-Specific Issues](#feature-specific-issues)
|
||
- [Comments (Giscus) not appearing](#comments-giscus-not-appearing)
|
||
- [Related posts broken](#related-posts-broken)
|
||
- [Code formatting issues](#code-formatting-issues)
|
||
- [Getting Help](#getting-help)
|
||
|
||
<!--te-->
|
||
|
||
## Deployment Issues
|
||
|
||
### Site fails to deploy on GitHub Pages
|
||
|
||
**Problem:** GitHub Actions shows an error when deploying.
|
||
|
||
**Solution:**
|
||
|
||
1. Check your repository **Actions** tab for error messages
|
||
2. Ensure you followed [Step 2 of QUICKSTART.md](QUICKSTART.md#step-2-configure-deployment-1-min) (Workflow permissions)
|
||
3. Verify your `_config.yml` has correct `url` and `baseurl`:
|
||
- Personal site: `url: https://username.github.io` and `baseurl:` (empty)
|
||
- Project site: `url: https://username.github.io` and `baseurl: /repo-name/`
|
||
4. Check that you're pushing to the `main` (or `master`) branch, NOT `gh-pages`
|
||
5. Commit and push a small change to trigger redeployment
|
||
|
||
**For YAML syntax errors:**
|
||
|
||
- Run `bundle exec jekyll build` locally to see the exact error
|
||
- Check for unquoted special characters (`:`, `&`, `#`) in YAML strings
|
||
|
||
---
|
||
|
||
### Custom domain becomes blank after deployment
|
||
|
||
**Problem:** You set a custom domain (e.g., `example.com`), but it resets to blank after deployment.
|
||
|
||
**Solution:**
|
||
|
||
1. Create a file named `CNAME` (no extension) in your repository root
|
||
2. Add your domain to it: `example.com` (one domain per line)
|
||
3. Commit and push
|
||
4. The domain will persist after future deployments
|
||
|
||
(See [DNS configuration instructions in INSTALL.md](INSTALL.md#deployment) for initial custom domain setup.)
|
||
|
||
---
|
||
|
||
### GitHub Actions: "Unknown tag 'toc'" error
|
||
|
||
**Problem:** Local build works, but GitHub Actions fails with `Unknown tag 'toc'`.
|
||
|
||
**Solution:**
|
||
|
||
1. Check your **Settings** → **Pages** → **Source** is set to `Deploy from a branch`
|
||
2. Ensure the branch is set to `gh-pages` (NOT `main`)
|
||
3. Wait 5 minutes and check Actions again
|
||
4. The issue usually resolves after you verify the gh-pages branch is set
|
||
|
||
---
|
||
|
||
## Local Build Issues
|
||
|
||
### Docker build fails
|
||
|
||
**Problem:** `docker compose up` fails or shows errors.
|
||
|
||
**Solution:**
|
||
|
||
1. Update Docker: `docker compose pull`
|
||
2. Rebuild: `docker compose up --build`
|
||
3. If still failing, check your system resources (disk space, RAM)
|
||
4. For M1/M2 Mac users, verify you're using a compatible Docker version
|
||
5. Check Docker Desktop is running
|
||
|
||
**For permission issues:**
|
||
|
||
- Linux users may need to add your user to the docker group: `sudo usermod -aG docker $USER`
|
||
- Then log out and log back in
|
||
|
||
---
|
||
|
||
### Ruby dependency issues
|
||
|
||
**Problem:** `Gemfile.lock` conflicts or bundle errors.
|
||
|
||
**Solution:**
|
||
|
||
1. Delete `Gemfile.lock`: `rm Gemfile.lock`
|
||
2. Update Bundler: `bundle update`
|
||
3. Install gems: `bundle install`
|
||
4. Try serving again: `bundle exec jekyll serve`
|
||
|
||
---
|
||
|
||
### Port already in use
|
||
|
||
**Problem:** "Address already in use" when running `jekyll serve`.
|
||
|
||
**Solution - Docker:**
|
||
|
||
```bash
|
||
docker compose down # Stop the running container
|
||
docker compose up # Start fresh
|
||
```
|
||
|
||
**Solution - Local Ruby:**
|
||
|
||
```bash
|
||
# Find and kill the Jekyll process
|
||
lsof -i :4000 | grep LISTEN | awk '{print $2}' | xargs kill
|
||
|
||
# Or specify a different port
|
||
bundle exec jekyll serve --port 5000
|
||
```
|
||
|
||
---
|
||
|
||
## Styling & Layout Problems
|
||
|
||
### CSS and JS not loading properly
|
||
|
||
**Problem:** Site looks broken: no colors, fonts wrong, links don't work.
|
||
|
||
**Common cause:** Incorrect `url` and `baseurl` in `_config.yml`.
|
||
|
||
**Solution:**
|
||
|
||
1. **Personal/organization site:**
|
||
|
||
```yaml
|
||
url: https://username.github.io
|
||
baseurl: # MUST be empty (not deleted)
|
||
```
|
||
|
||
2. **Project site:**
|
||
|
||
```yaml
|
||
url: https://username.github.io
|
||
baseurl: /repository-name/ # Must match your repo name
|
||
```
|
||
|
||
3. **Clear browser cache:**
|
||
- Chrome: `Ctrl+Shift+R` (Windows/Linux) or `Cmd+Shift+R` (Mac)
|
||
- Firefox: `Ctrl+F5` (Windows/Linux) or `Cmd+R` (Mac)
|
||
- Or open a private/incognito window
|
||
|
||
4. Redeploy: Make a small change and push to trigger GitHub Actions again
|
||
|
||
---
|
||
|
||
### Site looks broken after deployment
|
||
|
||
**Checklist:**
|
||
|
||
- [ ] Is `baseurl` correct (and not accidentally deleted)?
|
||
- [ ] Did you clear your browser cache?
|
||
- [ ] Wait 5 minutes for GitHub Pages to update
|
||
- [ ] Check GitHub Actions completed successfully
|
||
|
||
---
|
||
|
||
### Theme colors not applying
|
||
|
||
**Problem:** You changed `_config.yml` color settings but nothing changed.
|
||
|
||
**Solution:**
|
||
|
||
1. Check your color name is valid in `_sass/_variables.scss`
|
||
2. Clear browser cache (see above)
|
||
3. Rebuild: `docker compose up --build` (Docker) or `bundle exec jekyll build` (Ruby)
|
||
4. Wait for GitHub Actions to complete
|
||
5. Visit the site in a private/incognito window
|
||
|
||
---
|
||
|
||
## Content Not Appearing
|
||
|
||
### Blog posts not showing up
|
||
|
||
**Problem:** Created a post in `_posts/` but it's not on the blog page.
|
||
|
||
**Checklist:**
|
||
|
||
- [ ] Filename format is correct: `YYYY-MM-DD-title.md` (e.g., `2024-01-15-my-post.md`)
|
||
- [ ] File is in the `_posts/` directory (not in a subdirectory)
|
||
- [ ] Post has required frontmatter:
|
||
```markdown
|
||
---
|
||
layout: post
|
||
title: My Post Title
|
||
date: 2024-01-15
|
||
---
|
||
```
|
||
- [ ] Post date is NOT in the future (Jekyll doesn't publish future-dated posts by default)
|
||
- [ ] Blog posts are enabled in `_config.yml`: `blog_page: true`
|
||
|
||
**To fix:**
|
||
|
||
1. Check the filename format (uppercase, dashes, no spaces)
|
||
2. Verify the date is today or in the past
|
||
3. Rebuild: `bundle exec jekyll build` and check for error messages
|
||
|
||
---
|
||
|
||
### Publications not displaying
|
||
|
||
**Problem:** You added a BibTeX entry to `papers.bib` but it's not showing on the publications page.
|
||
|
||
**Checklist:**
|
||
|
||
- [ ] File is at `_bibliography/papers.bib`
|
||
- [ ] BibTeX syntax is correct (check for missing commas, unmatched braces)
|
||
- [ ] Entry has a unique citation key: `@article{einstein1905, ...}`
|
||
- [ ] Publication page is enabled: Check `publications_page: true` in `_config.yml`
|
||
|
||
**To debug BibTeX errors:**
|
||
|
||
```bash
|
||
# Local Ruby setup
|
||
bundle exec jekyll build 2>&1 | grep -i bibtex
|
||
|
||
# Docker
|
||
docker compose run --rm web jekyll build 2>&1 | grep -i bibtex
|
||
```
|
||
|
||
---
|
||
|
||
### Images not loading
|
||
|
||
**Problem:** Image paths broken or showing as missing.
|
||
|
||
**Common causes:**
|
||
|
||
- Wrong path in Markdown (use relative paths)
|
||
- Image file doesn't exist at the specified location
|
||
- Case sensitivity (Linux/Mac are case-sensitive)
|
||
|
||
**Solutions:**
|
||
|
||
1. **Correct path format:**
|
||
|
||
```markdown
|
||
|
||
```
|
||
|
||
2. **Check the file exists:**
|
||
- Personal images: `assets/img/`
|
||
- Paper PDFs: `assets/pdf/`
|
||
- Use lowercase filenames, no spaces
|
||
|
||
3. **For BibTeX PDF links:**
|
||
```bibtex
|
||
@article{mykey,
|
||
pdf={my-paper.pdf}, % File should be at assets/pdf/my-paper.pdf
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Configuration Issues
|
||
|
||
### YAML syntax errors
|
||
|
||
**Problem:** GitHub Actions fails with YAML error, or build is silent.
|
||
|
||
**Common mistakes:**
|
||
|
||
```yaml
|
||
# ❌ Wrong: Unquoted colons or ampersands
|
||
title: My Site: Research & Teaching
|
||
|
||
# ✅ Correct: Quote special characters
|
||
title: "My Site: Research & Teaching"
|
||
```
|
||
|
||
```yaml
|
||
# ❌ Wrong: Inconsistent indentation
|
||
nav:
|
||
- name: Home
|
||
url: /
|
||
- name: About # Extra space!
|
||
url: /about/
|
||
|
||
# ✅ Correct: Consistent 2-space indentation
|
||
nav:
|
||
- name: Home
|
||
url: /
|
||
- name: About
|
||
url: /about/
|
||
```
|
||
|
||
**To find errors:**
|
||
|
||
1. Use a YAML validator: [yamllint.com](https://www.yamllint.com/)
|
||
2. Run locally: `bundle exec jekyll build` shows the exact error line
|
||
3. Check that you didn't delete required lines (like `baseurl:`)
|
||
|
||
---
|
||
|
||
### Feed (RSS/Atom) not working
|
||
|
||
**Problem:** RSS feed at `/feed.xml` is empty or broken.
|
||
|
||
**Solution:**
|
||
|
||
1. Verify required `_config.yml` fields:
|
||
```yaml
|
||
title: Your Site Title
|
||
description: Brief description
|
||
url: https://your-domain.com # MUST be absolute URL
|
||
```
|
||
2. Ensure `baseurl` is correct
|
||
3. Check at least one blog post exists (with correct date)
|
||
4. Rebuild and wait for GitHub Actions to complete
|
||
|
||
---
|
||
|
||
### Search not working
|
||
|
||
**Problem:** Search box is empty or always returns nothing.
|
||
|
||
**Solution:**
|
||
|
||
1. Ensure search is enabled in `_config.yml`:
|
||
```yaml
|
||
search_enabled: true
|
||
```
|
||
2. Check that `_config.yml` has a valid `url` (required for search)
|
||
3. Rebuild the site
|
||
4. Search index is generated during build; give it a minute after push
|
||
|
||
---
|
||
|
||
## Feature-Specific Issues
|
||
|
||
### Comments (Giscus) not appearing
|
||
|
||
**Problem:** You enabled Giscus in `_config.yml` but comments don't show.
|
||
|
||
**Solution:**
|
||
|
||
1. Verify you have a GitHub repository for discussions (usually your main repo)
|
||
2. Check `_config.yml` has correct settings:
|
||
```yaml
|
||
disqus_shortname: false # Make sure this is false
|
||
giscus:
|
||
repo: username/repo-name
|
||
repo_id: YOUR_REPO_ID
|
||
category_id: YOUR_CATEGORY_ID
|
||
```
|
||
3. Visit [Giscus.app](https://giscus.app) to get your IDs and verify setup
|
||
4. Check the GitHub repo has Discussions enabled (Settings → Features)
|
||
|
||
---
|
||
|
||
### Related posts broken
|
||
|
||
**Problem:** Related posts feature crashes or shows errors.
|
||
|
||
**Solution:**
|
||
|
||
1. Related posts requires more gems. If you disabled it in `_config.yml`, that's fine:
|
||
```yaml
|
||
related_blog_posts:
|
||
enabled: false
|
||
```
|
||
2. If you want to enable it, ensure `Gemfile` has all dependencies installed:
|
||
```bash
|
||
bundle install
|
||
bundle exec jekyll build
|
||
```
|
||
|
||
---
|
||
|
||
### Code formatting issues
|
||
|
||
**Problem:** Code blocks don't have syntax highlighting or look wrong.
|
||
|
||
**Solution:**
|
||
|
||
1. Use proper markdown syntax:
|
||
|
||
````markdown
|
||
```python
|
||
# Your code here
|
||
print("hello")
|
||
```
|
||
````
|
||
|
||
2. For inline code:
|
||
|
||
```markdown
|
||
Use `code-here` for inline code.
|
||
```
|
||
|
||
3. Check that your language is supported by Pygments (Python, Ruby, JavaScript, etc. are all supported)
|
||
|
||
---
|
||
|
||
## Getting Help
|
||
|
||
If you're stuck:
|
||
|
||
1. **Check existing documentation:**
|
||
- [QUICKSTART.md](QUICKSTART.md) – Get started in 5 minutes
|
||
- [INSTALL.md](INSTALL.md) – Installation and deployment
|
||
- [CUSTOMIZE.md](CUSTOMIZE.md) – Full customization guide
|
||
- [FAQ.md](FAQ.md) – Frequently asked questions
|
||
|
||
2. **Search for your issue:**
|
||
- [GitHub Discussions](https://github.com/alshedivat/al-folio/discussions) – Q&A from community
|
||
- [GitHub Issues](https://github.com/alshedivat/al-folio/issues) – Bug reports and feature requests
|
||
|
||
3. **Get help from AI:**
|
||
- Use the **GitHub Copilot Customization Agent** (requires Copilot subscription) to get step-by-step help
|
||
- See [CUSTOMIZE.md § GitHub Copilot Customization Agent](CUSTOMIZE.md#github-copilot-customization-agent)
|
||
|
||
4. **Create a new discussion:**
|
||
- [Ask a question](https://github.com/alshedivat/al-folio/discussions/new?category=q-a) on GitHub
|
||
- Include error messages and what you're trying to do
|
||
|
||
---
|
||
|
||
**Most issues are resolved by:**
|
||
|
||
1. Checking `url` and `baseurl` in `_config.yml`
|
||
2. Clearing browser cache
|
||
3. Waiting for GitHub Actions to complete (~5 minutes)
|