How abdelmalek123-ennani/free-programming-books works
Project type and purpose
• This is an open-source, static content site (built with Jekyll) that aggregates and publishes “free programming books” and related learning resources in many languages.
• It’s essentially a curated content repository with a build pipeline that generates a static website and deploys it to GitHub Pages.
File structure
• Top-level directories:
• books, casts, courses, more – the Markdown content for each category.
• docs – contributor docs and Code of Conduct.
• scripts – helper tooling (e.g., rtl_ltr_linter.py).
• .github – CI workflows and custom GitHub Actions.
• _config.yml, _includes – Jekyll config and layout snippets.
• Key config/build files:
• _config.yml – site configuration for Jekyll.
• .github/workflows/*.yml – CI steps: link checks, linting, stale PR management.
• scripts/rtl_ltr_linter.py – checks for RTL/LTR consistency in translated files.
Relevant README insights
• Mentions a separate “dynamic search site” (hosted at /free-programming-books-search/) but that code lives elsewhere.
• Emphasizes the static site for browseable content.
• Points to contribution workflows (docs/CONTRIBUTING.md, HOWTO.md, CODE_OF_CONDUCT.md).
Main components & their relationships
a. Components
1. Developer Workstation – clones/forks the repo, writes/edits Markdown or code.
2. GitHub Repo – stores all Markdown content, Jekyll templates, scripts, CI configs.
3. Continuous Integration (GitHub Actions) – runs:
• Awesomebot link checks, broken-URL detector
• RTL/LTR linter (scripts/rtl_ltr_linter.py)
• Spell/format/lint (fpb-lint)
• Stale-PR and issue management
4. Static Site Generator (Jekyll) – processes Markdown + templates → HTML/CSS/JS.
5. Deployment (GitHub Pages) – hosts the generated static site at ebookfoundation.github.io/free-programming-books/.
6. End-User Browser – fetches static assets, displays the site.
b. Data flow & interactions
• Developer pushes changes → GitHub Repo → triggers CI workflows → on success, Jekyll build runs → artifacts deployed to GitHub Pages → users retrieve the site in their browsers.
• Scripts (rtl_ltr_linter, link checkers) run as part of CI, but do not alter production; they block merges on errors.
Architectural patterns & design principles
• Static site generation (SSG) for ultimate simplicity, performance, and low maintenance.
• GitOps/CI→CD: the entire process from content change to deployment is automated via GitHub Actions.
• Separation of concerns:
• Content (books/, courses/, etc.)
• Presentation (Jekyll templates, includes)
• Tooling (CI configs, scripts)
Detailed elements to capture
• .github/workflows (link‐checker, lint, stale PR…)
• scripts/rtl_ltr_linter.py as part of CI
• _config.yml & _includes used by Jekyll
• content directories (books/, casts/, courses/, more/) feeding into Jekyll
• deployment to GitHub Pages
• user browsing experience