# How the free-programming-books Repository Is Structured and Organized

> Discover how the free-programming-books repository is structured and organized. Learn about its language-centric Jekyll site, modular Markdown directories, and easy contribution process.

- Repository: [Free Ebook Foundation/free-programming-books](https://github.com/EbookFoundation/free-programming-books)
- Tags: architecture
- Published: 2026-02-23

---

**The free-programming-books repository follows a flat, language-centric Jekyll site structure that organizes thousands of learning resources into modular Markdown directories like `books/`, `courses/`, and `casts/`, enabling easy contribution and static site generation.**

The `EbookFoundation/free-programming-books` repository is a pure-content static site that aggregates freely available programming learning materials. Its architecture prioritizes readability and maintainability through a strict file-based hierarchy, allowing contributors to edit simple Markdown files while Jekyll handles the site rendering.

## Top-Level Repository Structure

The repository root contains configuration files, documentation, and entry points that define the project's behavior and community standards.

### Entry Point and Configuration

The [`README.md`](https://github.com/EbookFoundation/free-programming-books/blob/main/README.md) serves as the primary landing page, containing project badges, a quick introduction, and a condensed table of contents. The [`_config.yml`](https://github.com/EbookFoundation/free-programming-books/blob/main/_config.yml) file configures the Jekyll static site generator, specifying the theme, enabled plugins like `jekyll-relative-links` for internal link resolution, and build settings that allow the site to function both on GitHub Pages and in raw repository view.

### Legal and Community Guidelines

Standard governance files reside at the root level: `LICENSE` defines the legal terms, [`CODE_OF_CONDUCT.md`](https://github.com/EbookFoundation/free-programming-books/blob/main/CODE_OF_CONDUCT.md) establishes community standards, and [`CONTRIBUTING.md`](https://github.com/EbookFoundation/free-programming-books/blob/main/CONTRIBUTING.md) provides the contribution workflow. The `docs/` directory contains extended documentation including translation guides and detailed HOW-TO instructions.

## Content Organization by Media Type

Learning materials are segregated into four primary directories based on format, each following consistent internal formatting patterns.

### The books/ Directory

The `books/` directory stores the core data files listing free programming books. Resources are organized using two parallel classification schemes:

- **Language-centric files**: Named `free-programming-books-{lang}.md` (e.g., [`books/free-programming-books-en.md`](https://github.com/EbookFoundation/free-programming-books/blob/main/books/free-programming-books-en.md)), these contain resources specific to programming languages or human languages
- **Subject-centric files**: [`books/free-programming-books-subjects.md`](https://github.com/EbookFoundation/free-programming-books/blob/main/books/free-programming-books-subjects.md) holds language-agnostic resources like algorithms, software architecture, or theoretical computer science

Each file follows a rigid format: a level-2 heading for the category, followed by bullet lists where each entry contains the resource title, URL, and optional description.

### Courses, Casts, and Supplementary Materials

Three additional directories mirror the `books/` structure:

- **`courses/`**: Free online courses grouped by language (e.g., [`courses/free-courses-en.md`](https://github.com/EbookFoundation/free-programming-books/blob/main/courses/free-courses-en.md))
- **`casts/`**: Podcasts and screencast-style learning materials (e.g., [`casts/free-podcasts-screencasts-en.md`](https://github.com/EbookFoundation/free-programming-books/blob/main/casts/free-podcasts-screencasts-en.md))
- **`more/`**: Supplementary collections including cheat-sheets, interactive tutorials, problem sets, and coding playgrounds (e.g., [`more/free-programming-cheatsheets.md`](https://github.com/EbookFoundation/free-programming-books/blob/main/more/free-programming-cheatsheets.md))

## Classification System: Language vs. Subject

The repository implements a dual taxonomy to prevent resource duplication while maintaining discoverability. Language-specific resources reside in their respective `*-langs.md` files, keeping the lists focused and navigable. Subject-centric resources that transcend specific programming languages are isolated in [`books/free-programming-books-subjects.md`](https://github.com/EbookFoundation/free-programming-books/blob/main/books/free-programming-books-subjects.md), ensuring Python books do not clutter general computer science theory lists.

## Automation and Quality Control

Despite being a content repository, the project employs automated tooling to maintain formatting consistency across thousands of entries.

### Linting and Validation Scripts

The `scripts/` directory contains helper utilities used by the CI pipeline. The [`scripts/rtl_ltr_linter.py`](https://github.com/EbookFoundation/free-programming-books/blob/main/scripts/rtl_ltr_linter.py) script validates new entries for proper Right-to-Left (RTL) and Left-to-Right (LTR) text direction consistency, ensuring that mixed-language content displays correctly across different locales.

### GitHub Integration

The `.github/` directory houses GitHub-specific configurations including the Dependabot setup in [`.github/dependabot.yml`](https://github.com/EbookFoundation/free-programming-books/blob/main/.github/dependabot.yml) for dependency updates and pull request templates. GitHub Actions workflows automatically trigger the linter on pull requests, validating formatting before maintainers review submissions.

## Static Site Generation

The repository functions as a Jekyll site, converting the Markdown data files into a searchable, navigable website.

### Jekyll Configuration

The [`_config.yml`](https://github.com/EbookFoundation/free-programming-books/blob/main/_config.yml) declares the `jekyll-relative-links` plugin, which rewrites internal file references so that links resolve correctly whether viewed on GitHub.com or the rendered GitHub Pages site. This ensures that cross-references between the English book list and the courses list remain functional in both contexts.

### Asset Management

Visual assets for the generated site include `favicon.ico` at the root and HTML includes in `_includes/` (such as [`_includes/head-custom.html`](https://github.com/EbookFoundation/free-programming-books/blob/main/_includes/head-custom.html)) that inject custom metadata or tracking scripts into the site header.

## Programmatic Access Patterns

Developers interact with the repository structure through several common patterns:

Linking to specific sections from external Markdown:

```markdown
[Python free books](https://github.com/EbookFoundation/free-programming-books/blob/main/books/free-programming-books-en.md#python)

```

Fetching raw content via command line for local processing:

```bash
curl -s https://raw.githubusercontent.com/EbookFoundation/free-programming-books/main/books/free-programming-books-en.md | grep -i "flask"

```

Accessing the search index programmatically:

```javascript
fetch('https://ebookfoundation.github.io/free-programming-books-search/assets/search-index.json')
  .then(r => r.json())
  .then(index => {
    const results = index.filter(item => /flask/i.test(item.title));
    console.log(results);
  });

```

## Summary

- The repository uses a **flat content model** with no database or dynamic backend—only Markdown files processed by Jekyll
- Resources are organized by **media type** (`books/`, `courses/`, `casts/`, `more/`) and by **language** within each directory
- The **[`rtl_ltr_linter.py`](https://github.com/EbookFoundation/free-programming-books/blob/main/rtl_ltr_linter.py)** script enforces formatting standards and text direction consistency
- **Dual classification** separates language-specific tutorials from subject-agnostic theoretical content
- **Jekyll-relative-links** plugin ensures URLs work in both raw GitHub view and the rendered site

## Frequently Asked Questions

### What is the difference between the books/ and courses/ directories?

The `books/` directory contains textual resources like PDFs, ePubs, and online book-length documentation, while the `courses/` directory specifically indexes video-based tutorials, MOOCs, and structured online classes. Both follow identical Markdown formatting patterns but are separated to help users distinguish between reading material and video instruction.

### How does the repository handle resources in multiple languages?

Each language receives its own dedicated file within the relevant media directory (e.g., [`books/free-programming-books-en.md`](https://github.com/EbookFoundation/free-programming-books/blob/main/books/free-programming-books-en.md) for English, [`books/free-programming-books-es.md`](https://github.com/EbookFoundation/free-programming-books/blob/main/books/free-programming-books-es.md) for Spanish). This file-per-language approach allows localized communities to maintain their own lists without merge conflicts, while the [`rtl_ltr_linter.py`](https://github.com/EbookFoundation/free-programming-books/blob/main/rtl_ltr_linter.py) script ensures that Right-to-Left languages like Arabic or Hebrew display correctly alongside Left-to-Right content.

### Is there a database or API backend for the free-programming-books repository?

No, the repository maintains a **read-only data store** architecture with zero runtime dependencies. The "API" consists of raw GitHub URLs to Markdown files, and the search functionality is powered by a static JSON index generated at build time by Jekyll. This design ensures the resource list remains accessible even offline or in environments with restricted connectivity.

### What is the purpose of the scripts/rtl_ltr_linter.py file?

The [`scripts/rtl_ltr_linter.py`](https://github.com/EbookFoundation/free-programming-books/blob/main/scripts/rtl_ltr_linter.py) script is a CI utility that checks pull requests for proper Unicode directionality markers. It validates that Right-to-Left (RTL) script content (such as Arabic or Hebrew titles) includes appropriate directional formatting characters, preventing display corruption when the Jekyll site renders the content or when users view the raw Markdown on GitHub.