Improve README.md with user-friendly documentation and preserve during build process

[Copilot]

This PR replaces the auto-generated TypeScript API documentation in README.md with a comprehensive, user-friendly guide that includes project introduction, installation instructions, usage examples, and clear API documentation.

Changes Made

1. New User-Friendly README.md

Replaced the auto-generated TypeScript documentation with a structured README that includes:

• Project Introduction: Clear description of niddle as a "super fast Node.js addon for HTML parsing and manipulation, written in Rust"
• Features: Highlights key benefits like high-performance, simple JavaScript API, and Rust-based implementation
• Installation: Simple npm/yarn installation instructions
• Usage Examples: Practical code examples showing HTML parsing, node selection, and manipulation
• API Documentation: Concise but complete documentation for parse() function and NodeRepr class methods
• Contributing & Benchmarking: Instructions for development and performance testing

2. Build Process Improvements

Modified the documentation generation workflow to prevent overwriting the custom README:

• Updated docs script in package.json to generate API.md instead of overwriting README.md
• Added API.md to the files array so detailed API docs are included in npm packages
• Added reference to detailed API documentation in the main README

3. Accurate API Documentation

Ensured all API documentation matches the actual TypeScript definitions:

• Corrected append() method to only accept NodeRepr objects (not strings)
• Added proper return types including null for methods like select() and getAttribute()
• Verified all examples work correctly with the actual implementation

Testing

• All existing tests continue to pass
• New README examples have been validated to work correctly
• Build process (yarn docs) no longer overwrites the custom README
• Documentation generation still works for detailed API reference

The new README provides a much better developer experience while preserving the detailed auto-generated API documentation in a separate file for those who need it.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.