Mixed — Mixed signals — read the receipts

• Last commit 2d ago
• 79+ active contributors
• Distributed ownership (top contributor 6% of recent commits)
• CC-BY-4.0 licensed
• CI configured
• ⚠ Non-standard license (CC-BY-4.0) — review terms
• ⚠ No tests detected in the complete Git tree
• ⚠ Scorecard: default branch unprotected (0/10)

Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests, cross-checked against OpenSSF Scorecard

A curated, community-maintained catalog of free programming books and learning resources organized by language (40+ languages) and topic, published as both Markdown files in the books/ directory and served via a dynamic search interface at ebookfoundation.github.io. It aggregates freely available books, tutorials, and educational materials from across the web with working links and minimal curation to ensure quality. Flat structure: books/ directory contains 40+ language-specific markdown files (free-programming-books-{lang-code}.md) structured as categories → book lists with title, author, and URL; parallel casts/ directory mirrors this for podcasts/screencasts. _config.yml configures Jekyll for GitHub Pages hosting, and _includes/head-custom.html provides custom styling. No monorepo or application code—pure content organized by language code.

LLM-derived; treat as a starting point, not verified fact.

Self-taught programmers, students, educators, and developers in non-English speaking countries who want free, vetted learning materials in their native language; also contributors who add, verify, and maintain book listings across language communities.

LLM-derived; treat as a starting point, not verified fact.

Highly mature and community-driven: 50k+ stars on GitHub, originating from a 2011 StackOverflow post, with active global contribution across 40+ language files (free-programming-books-{lang}.md). The project shows sustained maintenance with regular PR merges, but exact commit recency and test coverage are not visible from the provided metadata—typical for a curated content repo rather than software library.

Standard open source risks apply.

LLM-derived; treat as a starting point, not verified fact.

Active community contribution visible through Hacktoberfest 2025 stats badge and continuous PR merging for new book additions and URL updates across language files. The project is in steady-state maintenance mode: accepting contributions to existing language files, occasionally adding new languages, and keeping the dynamic search site (separate repository) synchronized.

LLM-derived; treat as a starting point, not verified fact.

Clone the repository: git clone https://github.com/EbookFoundation/free-programming-books.git then cd free-programming-books. No build or installation step required—content is plain markdown. To preview the Jekyll site locally: bundle install && bundle exec jekyll serve (requires Ruby/Jekyll installed). Edit markdown files directly and test by viewing changes in your text editor or via the Jekyll preview.

Daily commands: To run the Jekyll preview locally: cd free-programming-books && bundle install && bundle exec jekyll serve --livereload. Site will be available at http://localhost:4000. To validate markdown syntax without serving: use any markdown linter. No runtime dependencies, build process, or environment variables required.

• README.md — Primary entry point documenting the project's mission, structure, and contribution guidelines for all languages and content types.
• books/free-programming-books-en.md — Canonical English reference file establishing the markdown structure, categorization schema, and link format that all other language variants must follow.
• books/free-programming-books-langs.md — Master index listing all supported languages and their corresponding file mappings, essential for navigation and language discovery.
• books/free-programming-books-subjects.md — Subject-based organization file providing cross-language topic indexing and discovery mechanism for learners.
• _config.yml — Jekyll configuration file controlling site build, theme, and deployment settings for GitHub Pages hosting.
• books/free-programming-books-zh.md — Demonstrates multi-byte language support and serves as template for non-Latin script implementations.

• Language-specific book lists (Markdown) — Each free-programming-books-[lang].md file maintains curated, categorized book links for one language.
  • Failure mode: Broken links, outdated resources, or inconsistent formatting reduces discoverability and trust.
• Language index (langs.md) (Markdown with structured reference links) — Master registry mapping language codes to book/course/cast files for navigation.
  • Failure mode: Missing or incorrect language mappings prevent users from finding content in their language.
• Subject index (subjects.md) (Markdown link aggregation) — Cross-language topic organization enabling discovery by programming skill/domain rather than language.
  • Failure mode: Stale or incomplete subject categorization reduces accessibility for topic-focused learners.
• Jekyll/GitHub Pages build pipeline (Jekyll, GitHub Actions, GitHub Pages) — Renders markdown to static HTML and deploys to web via GitHub Pages automation.
  • Failure mode: Build failures or misconfigurations prevent site updates; no fallback rendering mechanism.
• External search engine (Separate search implementation (not in this repo)) — Separate ebookfoundation search site indexes and provides full-text query over markdown content.
  • Failure mode: Search unavailable; users must browse static site or language indexes.
• Course and podcast catalogs (Markdown) — Parallel free-courses-[lang].md and free-podcasts-screencasts-[lang].md files organizing educational media.
  • Failure mode: Outdated or broken media links reduce value for learners seeking alternative content formats.

• Contributor via GitHub → books/free-programming-books-[lang].md — Pull requests add or update book entries and links.
• Markdown content files → Jekyll build process — Jekyll parses all markdown and converts to HTML during site generation.
• Static HTML output → GitHub Pages CDN — Rendered HTML deployed globally via GitHub Pages for low-latency access.
• GitHub Pages HTML → External search indexer — Separate search service crawls and indexes site content for query fulfillment.
• User queries → ebookfoundation search site — Users search by language, subject, or keyword via the dedicated search interface.

Add a New Programming Book to English List

1. Open the English books file for editing (books/free-programming-books-en.md)
2. Find the appropriate subject category (e.g., Web Development, Machine Learning) or create one following the existing markdown header format (### Category Name) (books/free-programming-books-en.md)
3. Add a new link entry following the pattern: * Book Title - Brief description (Author if known) (books/free-programming-books-en.md)
4. Verify the link is active and book is genuinely free before submitting a pull request (books/free-programming-books-en.md)

Translate Books List to a New Language

1. Copy the English books file to a new language variant file (e.g., free-programming-books-pt.md for Portuguese) (books/free-programming-books-en.md)
2. Translate all category headers, descriptions, and metadata while preserving link URLs (books/free-programming-books-[lang].md)
3. Add new language entry to the master language index file (books/free-programming-books-langs.md)
4. Submit pull request with new language variant following contribution guidelines from README (README.md)

Add a New Course Resource

1. Open the appropriate language courses file (or create if missing) (courses/free-courses-en.md)
2. Locate the subject category or add new category header following markdown conventions (courses/free-courses-en.md)
3. Append course entry with title, URL, and brief description in list format (courses/free-courses-en.md)
4. Verify course is currently free and active before submitting contribution (courses/free-courses-en.md)

• Markdown (.md files) — Human-readable, version-control friendly format enabling decentralized contributions via Git/GitHub.
• Jekyll + GitHub Pages — Zero-cost hosting, automatic builds from markdown, familiar workflow for open-source contributors.
• Git/GitHub — Enables collaborative curation, change tracking, and community contributions at scale across 50+ languages.
• Static site generation — No backend required; eliminates scalability concerns and security surface for a read-heavy resource directory.

• Markdown-based content instead of database

  • Why: Simplicity and decentralized editing workflow via GitHub PRs
  • Consequence: Limited dynamic search/filtering (offloaded to separate search site), manual content synchronization across languages.

• Language-specific files rather than single polyglot file

  • Why: Easier translation management and independent language community ownership
  • Consequence: Content duplication; must maintain consistency across 50+ files manually.

• GitHub-hosted static content without backend APIs

  • Why: Eliminates infrastructure costs and complexity
  • Consequence: Search functionality requires separate external implementation (ebookfoundation.github.io/search).

• Does not provide real-time content moderation or automated link validation.
• Does not include user authentication, preferences, or personalization.
• Does not host book files directly; only curates and links to external resources.
• Not designed for automated content ingestion; curation is manual and community-driven.
• Does not track download statistics or usage metrics per resource.

• Avg cyclomatic complexity: ~2 — Repo is primarily static content curation with no algorithmic complexity; structure is flat directory of markdown files with simple Jekyll templating.
• Largest file: books/free-programming-books-en.md (3,500 lines)
• Estimated quality issues: ~4 — No code per se; issues are content consistency (duplicate links, broken URLs, inconsistent formatting across language variants) and process gaps (no automated validation).

• Inconsistent link format across languages (Medium) — books/free-programming-books-*.md (multiple files): Some language variants use different markdown link syntax or list formatting, making cross-language tooling fragile.
• Duplicate content across 50+ language files (High) — books/ and courses/ and casts/ directories: Maintaining synchronized content updates across all language variants is error-prone; changes in English may not propagate.
• No automated link validation in CI (Medium) — Repository (missing step): Dead or redirected links can accumulate since contributions are not checked for URL viability before merge.
• Manual language index maintenance (Low) — books/free-programming-books-langs.md: New language files must be manually registered in langs.md; missing or stale entries prevent discoverability.

• GitHub PR review process (Manual review bottleneck) — All contributions require human review; no automated quality gates for link validity, formatting, or duplication.
• Content duplication across 50+ language files (Synchronization overhead) — Updates to structure or shared entries must be replicated manually in every language variant.
• Search functionality (external) (Feature decomposition) — Search relies on a separate external implementation; this repo has no native indexing or query capability.
• Markdown parsing and rendering (Build time scaling) — Jekyll build processes all markdown; large repo growth (current 244 files) may slow site regeneration.

No hidden technical traps typical of a content repository. Main gotchas: (1) Link verification is manual—no automated CI checks for URL liveness, so broken links persist until caught by contributors; (2) Language code inconsistencies: some use ISO 639-1 codes (en, fr), others use regional variants (pt_BR, zh) with underscores, requiring careful naming when adding new languages; (3) Markdown formatting must be strict for Jekyll rendering and search indexing—inconsistent spacing in [Title](url) - Author format breaks parsing; (4) No central schema validation, so book entries can drift in format across different language files unless manually reviewed.

• Markdown-as-Source-of-Truth — In this repo, plain markdown files are both the primary data store and publication source; understanding how markdown structure directly maps to Jekyll HTML output and search indexing is critical for maintaining consistency
• Static Site Generation (SSG) / Jekyll — The repo uses Jekyll to transform markdown into a static HTML site hosted on GitHub Pages with no runtime server; this is why contributions are pull requests on markdown files, not database inserts
• Language Localization via File Naming Convention — Multilingual content is organized using ISO 639 language codes and regional suffixes (pt_BR vs pt_PT) embedded in filenames rather than a unified database; maintaining this pattern is essential when adding new languages
• Link Rot & Content Decay — A curated links catalog naturally decays as external resources move or disappear; understanding this problem and the manual effort required to maintain it is why community contribution is essential to this project's longevity
• Community Curation vs Algorithmic Indexing — This project relies on human reviewers to validate books are free and quality, not automated crawling; this creates bottlenecks but ensures higher signal-to-noise ratio than algorithmic search engines
• Hacktoberfest Community Events — The repo uses Hacktoberfest stats badges to encourage October contribution surges; understanding how seasonal events drive spikes in community maintenance is relevant to onboarding and release timing
• GitHub Pages Publishing Pipeline — Changes to the books/ markdown files automatically trigger Jekyll rebuild and publish to ebookfoundation.github.io; this means PRs are the only deployment mechanism and there is no staging environment for testing

• EbookFoundation/free-programming-books-search — Official companion repo providing the dynamic full-text search interface for this book catalog; indexes and serves the markdown content with JavaScript frontend
• awesome-selfhosted/awesome-selfhosted — Similar community-curated list format for self-hosted software alternatives; demonstrates same content-first, link-aggregation approach applied to infrastructure tools
• sindresorhus/awesome — Parent list of curated GitHub awesome lists; establishes the 'awesome list' format and community standards that free-programming-books follows and references
• github/gitignore — Parallel large-scale, community-maintained GitHub reference repo with 100k+ stars; demonstrates how GitHub excels at distributed curation of content, not code
• torvalds/linux — Historical predecessor: the free-programming-books project itself originated as a clone of a StackOverflow answer and grew into an independent reference, mirroring how open-source communities evolve knowledge assets

• Verify and fix dead links in one language file: Pick books/free-programming-books-{language}.md, test 10–20 book URLs, and submit a PR removing or updating broken links with working alternatives. Low barrier, high impact for maintainability.
• Standardize author attribution format: Some entries use - [Title](url) without author, others use - [Title](url) - Author. Pick a language file and audit, then propose a consistent format PR with examples of before/after consistency.
• Add missing language to free-programming-books-langs.md index: Check if a new language file exists (e.g., free-programming-books-it.md) but is not listed in the master langs.md registry, then add it with a PR. One-line contribution with quick win.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub