nhcarrigan/docs
11
0
Fork 0
generated from nhcarrigan/template
Code Issues 2 Pull Requests 7 Actions Releases 1 Activity
Files
78ea7cc209b1be1bdf763a7e3d976d57bff2acc9
docs/src/content/docs/projects/freecodecamp-review-generator.md
T
naomi 1ad784344c
Node.js CI / Lint and Test (push) Failing after 34s
Details
feat: add new projects to documentation
2025-10-31 21:27:00 -07:00

15 KiB
Raw Blame History

title
title
freeCodeCamp Review Generator

freeCodeCamp Review Generator (hereinafter the "Application") is a command-line tool that aggregates all review lesson pages from freeCodeCamp's Full Stack Developer curriculum into a single, comprehensive PDF document for offline study and reference.

1. User Documentation

This section is for those interacting with a live instance of the Application.

Overview

The Application generates a compiled PDF document containing all review pages from freeCodeCamp's Full Stack Developer curriculum. The generated PDF includes:

  • A custom cover page with generation date
  • An automatically generated table of contents with links to each review section
  • All review content organized according to the curriculum structure
  • Custom headers and footers for easy navigation
  • Page numbers and links to community resources

Generated PDF Structure

The output PDF (fcc-review-pages.pdf) follows the freeCodeCamp curriculum structure:

  1. HTML Topics - Reviews covering basic HTML, semantic HTML, forms and tables, and accessibility
  2. CSS Topics - Reviews covering basic CSS, layout (Flexbox, Grid), styling, responsive design, animations, and more
  3. JavaScript Topics - Reviews covering variables, functions, arrays, objects, DOM manipulation, asynchronous programming, and more
  4. Frontend Libraries - Reviews covering React fundamentals, state management, routing, and frontend frameworks
  5. Python Topics - Reviews covering Python basics, data structures, algorithms, and object-oriented programming
  6. Relational Databases - Reviews covering SQL, Bash scripting, and Git

What to Expect

Each review page in the generated PDF contains:

  • Topic headings - Clear section markers for each subject
  • Code examples - Syntax-highlighted code snippets demonstrating concepts
  • Explanations - Detailed descriptions of programming concepts and best practices
  • Reference material - Quick-reference information for common patterns and methods

Output Format

  • File name: fcc-review-pages.pdf
  • Page format: Legal size (8.5" x 14")
  • Margins: 0.75 inches on all sides
  • Header: Displays "Naomi's freeCodeCamp Review"
  • Footer: Contains page numbers and link to community Discord server

Disclaimer

This is not an officially sanctioned freeCodeCamp document. The Application is maintained independently and the generated content reflects the curriculum state at the time of generation. For the most up-to-date information, always refer to the official freeCodeCamp website.

2. Technical Documentation

This section is for those interested in running their own instance of the Application.

Prerequisites

  • Node.js: Version 18.x or higher recommended
  • pnpm: Package manager (version 10.18.0 or compatible)
  • Operating System: Linux, macOS, or Windows
  • Disk Space: Minimum 500MB for dependencies and output files

Installation

  1. Clone the repository:

    git clone <repository-url>
cd fcc-review-generator

  2. Install dependencies:

    pnpm install

    This will automatically install Chrome browser via Puppeteer (required for PDF generation).

Directory Structure

fcc-review-generator/
├── content/              # Review lesson markdown files
│   └── review-*/         # Individual review topic directories
├── data/
│   └── order.json        # Curriculum ordering configuration
├── src/
│   ├── config/
│   │   ├── options.ts    # PDF generation options
│   │   └── text.ts       # Cover page text template
│   └── index.ts          # Main application entry point
├── package.json          # Project dependencies and scripts
└── tsconfig.json         # TypeScript configuration

Configuration

Content Source

  1. Copy review lesson markdown files from the freeCodeCamp repository to the content/ directory
  2. The Application recursively walks the directory tree, so nested folders are supported
  3. Only .md files are processed; other files are ignored

Curriculum Ordering

  1. Copy the Full Stack curriculum order from /curriculum/structure/superblocks/fullstack.json in the freeCodeCamp repository
  2. Paste into data/order.json in this project
  3. The Application uses this to sort review pages in the correct curriculum order

PDF Customization

Modify src/config/options.ts to customize:

  • Page size and margins
  • Header and footer templates
  • Styling and formatting

Modify src/config/text.ts to customize:

  • Cover page content
  • Introduction text
  • Disclaimer text

Usage

Run the Application:

pnpm start

The Application will:

  1. Read all markdown files from content/ directory
  2. Sort them according to data/order.json
  3. Generate a table of contents
  4. Compile all content into a single markdown file (review.md)
  5. Convert the markdown to PDF (fcc-review-pages.pdf)
  6. Clean up the temporary markdown file

Output

  • Success: Generates fcc-review-pages.pdf in the project root
  • Console: Displays progress messages during execution
  • Errors: Logged to console with descriptive messages

Development

Build TypeScript

pnpm build

Compiles TypeScript files according to tsconfig.json.

Linting

pnpm lint

Runs ESLint with strict settings (max warnings: 0).

Testing

pnpm test

Currently outputs a placeholder message (no tests implemented).

Technical Architecture

Core Components

  1. File Reader (readDirectoryRecursively)

    • Recursively scans the content directory
    • Returns flat array of file paths
    • Handles nested directory structures

  2. File Sorter (sortFiles)

    • Sorts files based on curriculum order from order.json
    • Matches file directory names to curriculum block names
    • Maintains proper curriculum sequence

  3. Content Processor (rollupFiles)

    • Extracts frontmatter metadata (title, ID, etc.)
    • Strips frontmatter and freeCodeCamp-specific heading syntax
    • Generates table of contents with anchor links
    • Compiles all content into single markdown file

  4. PDF Generator (createPdf)

    • Uses md-to-pdf library (which uses Puppeteer/Chrome)
    • Applies custom styling and layout options
    • Generates headers, footers, and page numbers
    • Writes final PDF to disk

Dependencies

  • md-to-pdf (v5.2.4): Markdown to PDF conversion using headless Chrome
  • tsx (v4.20.6): TypeScript execution for development
  • typescript (v5.9.3): TypeScript compiler
  • eslint (v9.37.0): Code quality and style enforcement

Troubleshooting

Common Issues

Issue: Puppeteer/Chrome installation fails

  • Solution: Ensure you have sufficient disk space and network connectivity. Run pnpx puppeteer browsers install chrome manually.

Issue: PDF generation fails with "Protocol error"

  • Solution: Chrome may need additional system dependencies. On Linux, install required libraries for headless Chrome.

Issue: Files not appearing in correct order

  • Solution: Verify data/order.json matches the structure of your content directory names.

Issue: Out of memory errors

  • Solution: The Application processes all content in memory. For very large datasets, consider increasing Node.js memory limit: NODE_OPTIONS="--max-old-space-size=4096" pnpm start

Performance Considerations

  • File processing is sequential for consistent ordering
  • PDF generation uses headless Chrome, which is memory-intensive
  • Typical generation time: 10-30 seconds depending on content volume
  • Temporary markdown file is automatically cleaned up after PDF generation

System Requirements

  • Memory: Minimum 2GB RAM (4GB recommended)
  • CPU: Modern multi-core processor recommended
  • Network: Required for initial dependency installation
  • Storage: 500MB minimum for dependencies and output

3. Legal Documentation

This section is for expansions to our legal policies specific to the Application.

License

This software is licensed under Naomi's Public License. The full license text can be found at:

Copyright is held by Naomi Carrigan.

Privacy Policy

The Application processes markdown files locally and does not collect, store, or transmit any personal data. For information about privacy practices related to the project infrastructure (repository hosting, issue tracking, etc.), please refer to:

Terms of Service

By using this Application, you agree to the Terms of Service. The full terms can be found at:

Security Policy

If you discover a security vulnerability in the Application, please follow the responsible disclosure process outlined in our Security Policy:

Content Attribution

The review content processed by this Application originates from freeCodeCamp.org and is subject to freeCodeCamp's licensing terms. This tool is an unofficial aggregator and is not endorsed by or affiliated with freeCodeCamp.org.

Users of the generated PDF should respect freeCodeCamp's intellectual property rights and use the content for personal educational purposes only.

Disclaimer of Warranty

THE APPLICATION IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. THE MAINTAINERS MAKE NO WARRANTY THAT:

  • The generated PDF will be error-free or complete
  • The content will be current or up-to-date with the latest freeCodeCamp curriculum
  • The Application will function without interruption

Users should always refer to the official freeCodeCamp website for the most accurate and current curriculum information.

4. Contributing Documentation

This section is for documentation related to contributing to the Application's codebase.

Getting Started

We welcome contributions to the freeCodeCamp Review Generator! Before contributing, please review:

  1. Contributing Guidelines: https://docs.nhcarrigan.com/#/contributing
  2. Code of Conduct: https://docs.nhcarrigan.com/#/coc

Ways to Contribute

1. Report Bugs

If you encounter a bug, please open a GitHub issue with:

  • Clear description of the problem
  • Steps to reproduce
  • Expected vs. actual behavior
  • Your environment (OS, Node.js version, pnpm version)
  • Any relevant error messages or logs

2. Suggest Enhancements

We appreciate feature requests and enhancement suggestions! Please open a GitHub issue describing:

  • The problem you're trying to solve
  • Your proposed solution
  • Any alternative approaches you've considered
  • How this would benefit other users

3. Submit Pull Requests

Ready to contribute code? Follow these steps:

  1. Fork and Clone

    git clone <your-fork-url>
cd fcc-review-generator

  2. Create a Branch

    git checkout -b feature/your-feature-name

  3. Make Changes

    • Follow existing code style and patterns
    • Update relevant documentation
    • Ensure TypeScript types are correct
    • Test your changes thoroughly

  4. Run Quality Checks

    pnpm lint    # Check code style
pnpm build   # Ensure TypeScript compiles
pnpm start   # Test PDF generation

  5. Commit Changes

    git add .
git commit -m "feat: description of your changes"

    Follow conventional commit message format:

    • feat: for new features
    • fix: for bug fixes
    • docs: for documentation changes
    • refactor: for code refactoring
    • chore: for maintenance tasks

  6. Push and Create PR

    git push origin feature/your-feature-name

    Then open a Pull Request on GitHub with a clear description of your changes.

Code Style Guidelines

  • TypeScript: Use strict type checking; avoid any types
  • Formatting: Follow the ESLint configuration (@nhcarrigan/eslint-config)
  • Naming: Use descriptive variable and function names
  • Comments: Include JSDoc comments for exported functions
  • Error Handling: Use try-catch blocks and provide meaningful error messages

Project Conventions

Copyright Headers

All source files should include the copyright header:

/**
 * @copyright NHCarrigan
 * @license Naomi's Public License
 * @author Naomi Carrigan
 */

File Organization

  • Place configuration in src/config/
  • Keep utility functions modular and focused
  • Use ES modules (import/export)
  • Maintain clear separation of concerns

TypeScript Configuration

The project uses strict TypeScript settings:

  • strict: true
  • Target: ES2022
  • Module: ESNext
  • No implicit any types

Testing

Currently, the project does not have an automated test suite. Contributions that add testing infrastructure are welcome! Potential testing improvements:

  • Unit tests for file processing functions
  • Integration tests for PDF generation
  • Snapshot tests for output consistency
  • CI/CD pipeline integration

Development Workflow

  1. Install dependencies: pnpm install
  2. Make changes to source files in src/
  3. Test locally: pnpm start to verify PDF generation
  4. Check for errors: pnpm lint and pnpm build
  5. Commit and push your changes
  6. Create Pull Request for review

Review Process

Pull requests will be reviewed by project maintainers. The review process includes:

  • Code quality and style verification
  • Functionality testing
  • Documentation completeness
  • Alignment with project goals

Please be patient during the review process and be open to feedback and requested changes.

Communication

For questions, discussions, or help with contributions:

Recognition

All contributors will be recognized for their contributions. Significant contributions may result in being listed in a CONTRIBUTORS file or project documentation.

License for Contributions

By contributing to this project, you agree that your contributions will be licensed under the same license as the project (Naomi's Public License). You confirm that:

  • You have the right to submit the contribution
  • Your contribution is your original work or properly attributed
  • You understand the contribution will be publicly available

Thank you for your interest in contributing to the freeCodeCamp Review Generator! Your contributions help make this tool better for everyone in the learning community.

Reference in New Issue View Git Blame Copy Permalink