What File Formats Are Permissible for Resource Entries in Free Programming Books

The Free Programming Books repository strictly permits PDF, HTML, ePub, GitBook-based sites, and Git repositories for book entries, with specific formatting syntax enforced by automated CI linting.

The EbookFoundation/free-programming-books repository maintains rigorous standards to ensure all contributed resources remain accessible and consistently formatted. When submitting programming books or educational materials, contributors must use only the file formats explicitly allowed in the contribution guidelines, along with precise Markdown syntax that automated validators can parse.

Permissible File Formats for Books

According to docs/CONTRIBUTING.md (lines 23-24), the repository accepts exactly five format types for book resources:

• PDF – Portable Document Format for offline reading
• HTML – Directly viewable web-page format
• ePub – Electronic publication standard for e-readers
• gitbook.io-based site – Online books hosted on the GitBook platform
• Git repository – Source repositories containing book files (Markdown, LaTeX, or source code)

These formats ensure broad accessibility while maintaining the repository's commitment to open, vendor-neutral standards.

Formatting Conventions and Syntax Rules

The repository enforces strict Markdown structure to maintain consistency across thousands of entries. The guidelines in docs/CONTRIBUTING.md (lines 99-118) specify exact placement and spacing requirements.

Author and Format Placement

The author name must always precede the format note, with exactly one space between the closing parenthesis of the link and the opening parenthesis of the format identifier. The correct pattern is:

* [Title](URL) - Author Name (Format)

Handling Multiple Formats

When a resource exists in multiple permissible formats, contributors have two valid approaches:

1. Separate entries: Create distinct list items for each format variant
2. Combined notation: List multiple formats within a single entry using comma separation: (HTML, PDF)

Both methods require that each format identifier matches the allowed list recognized by the linter.

Automated Validation and Linting

Format compliance is enforced automatically through the repository's CI pipeline. The .github/workflows/fpb-lint.yml workflow executes validation scripts on every pull request.

The scripts/rtl_ltr_linter.py file (lines 57-58) contains an ignore_meta list that explicitly recognizes PDF, EPUB, and HTML as valid metadata tags. This allows the linter to distinguish between permissible format notes and other text that might violate formatting rules, ensuring only standardized entries reach the main branch.

Practical Code Examples

Below are correctly formatted entries demonstrating the permissible formats in action:

* [Learn Python the Hard Way (2nd Edition)](https://learnpythonthehardway.org/python3/) - Zed Shaw (HTML)
* [Learn Python the Hard Way (2nd Edition)](https://learnpythonthehardway.org/python3/learn-python-the-hard-way.pdf) - Zed Shaw (PDF)
* [Learn Python the Hard Way (2nd Edition) – ePub](https://learnpythonthehardway.org/python3/learn-python-the-hard-way.epub) - Zed Shaw (ePub)
* [Learn Python the Hard Way (Git repo)](https://github.com/zedshaw/learn-python-the-hard-way) - Zed Shaw (Git)

Example of combined format notation for a single resource:

* [The Rust Programming Language](https://doc.rust-lang.org/book/) - Steve Klabnik & Carol Nichols (HTML, PDF)

Summary

• The repository accepts PDF, HTML, ePub, GitBook sites, and Git repositories as the only permissible file formats for book entries.
• Format notes must follow the author name with a single space between the link and the format identifier, as strictly defined in docs/CONTRIBUTING.md.
• Multiple formats can be listed as separate entries or combined using comma-separated notation like (HTML, PDF).
• Automated validation via scripts/rtl_ltr_linter.py and the .github/workflows/fpb-lint.yml CI workflow enforces these standards by checking entries against the approved ignore_meta list.
• Only freely accessible resources are permitted; any format requiring payment, login credentials, or restrictive licensing is prohibited.

Frequently Asked Questions

Can I submit a book that requires a paid subscription to access?

No. The repository only accepts free resources. Any format that requires a paid subscription, user login, or restrictive license violates the contribution guidelines and will be rejected by maintainers and automated checks.

How do I format an entry when a book is available in both PDF and HTML?

You can either create two separate list items—one marked (PDF) and one marked (HTML)—or use a combined format note like (HTML, PDF) in a single entry. Both approaches are valid as long as the author name precedes the format note and a single space separates the link from the format identifier.

Are Microsoft Word (.docx) or other proprietary formats allowed?

No. The permissible formats are strictly limited to PDF, HTML, ePub, GitBook-based sites, and Git repositories as explicitly listed in docs/CONTRIBUTING.md. Proprietary formats like .docx are not supported by the repository's linting system and will fail validation.

Where does the repository enforce these file format rules?

The rules are enforced automatically by the CI workflow defined in .github/workflows/fpb-lint.yml, which executes the scripts/rtl_ltr_linter.py script. This linter checks the "ignore_meta" list (lines 57-58) to validate that only recognized format identifiers like PDF, EPUB, and HTML are used.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}