Setting up sidebar navigation for Jekyll documentation site on GitHub Pages

[Emma_Galaxy]

I’m trying to build a documentation site for my team’s project using GitHub Pages with Jekyll. I’ve got the basic setup working but I’m stuck on creating a proper navigation menu.

My current project structure looks like this:

project-root/
├── _config.yml
├── index.md
├── overview.md
├── README.md
└── guides/
    ├── getting-started.md
    └── advanced-usage.md

Here’s what I have in my configuration:

title: Project Documentation
description: Complete guide for our application
baseurl: '/project-docs'
markdown: kramdown
highlighter: rouge
plugins:
  - jekyll-sitemap

# Menu items
menu_items:
  - name: Guides
    link: /guides
    local: true

The main issues I’m facing are:

• How do I create a sidebar that shows up on all pages
• What’s the proper way to structure my markdown files so Jekyll can find them
• How to make the navigation actually work and link between pages

I’ve seen other Jekyll sites with nice left sidebars but can’t figure out how to implement one myself. Any help would be great!

[alexj]

Honestly, start with the minima theme and customize it. It’s got sidebar support already built in. Just add theme: minima to your config and make a _sass folder for your custom styles. Way easier than building everything from scratch.

[joec]

I hit the same problems setting up docs for our company tools. Jekyll needs a proper layout system to keep your sidebar consistent across pages. Start by creating a _layouts directory in your root folder with a default.html file. This layout holds your sidebar HTML and applies to all pages. In your markdown files, add layout: default to the front matter. For sidebar navigation, you can loop through menu_items using Liquid templating. But I’ve found Jekyll’s collections feature way more maintainable than manually defining menu items in _config.yml. Just create a _data folder with a navigation YAML file for your menu structure. Jekyll automatically converts markdown files from your root directory and subdirectories. Each markdown file needs front matter with at least a title and layout. Your guides folder should work fine, but I’d add an index.md file inside it for better organization. One gotcha: relative links break depending on your baseurl config. Use {{ site.baseurl }} in your links to avoid deployment issues on GitHub Pages.

[SwimmingShark]

Getting a proper sidebar working in Jekyll took me weeks when I started. Here’s what finally clicked for me. Use includes with your layout structure. Make an _includes folder and drop your sidebar HTML into sidebar.html. Then just call it in your default layout: {% include sidebar.html %}. For navigation, skip the manual setup and use Jekyll’s automatic page discovery instead. Loop through site.pages and filter by directory or front matter variables: {% for page in site.pages %} works great for dynamic menus. The CSS positioning caught me off guard. Your sidebar needs proper fixed positioning, and your main content needs left margin or padding to compensate. One heads up - GitHub Pages limits which plugins you can use, so stick to the supported ones. Your current structure looks fine, but add a permalink to your front matter for cleaner URLs. Also, baseurl configuration gets messy with relative paths. Test everything locally before pushing to GitHub Pages.