diff --git a/README.md b/README.md index 7fe6115..112532b 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,39 @@ -# README.md -# Astro Documentation to PDF Converter +# Astro Documentation PDF Generator -A Python script that automatically generates a well-formatted PDF from Astro's documentation repository. The script clones the documentation, processes all markdown files, and creates a PDF with a table of contents, proper formatting, and consistent styling. +A Python script to generate a PDF from Astro's documentation. Forked from [Docs-Exporter](https://github.com/Riyooo/Docs-Exporter) and modified to work with Astro's documentation format. -## Features +## Overview -- Automatic repository cloning and updating -- Comprehensive documentation processing -- Table of contents generation -- Code block syntax highlighting -- Image path handling -- Proper page breaks -- Custom header and footer -- Error handling and recovery -- Progress reporting -- Clean temporary file management +This script: +- Clones the Astro documentation repository +- Processes Markdown/MDX files +- Generates a PDF with: + - Cover page + - Table of contents + - Formatted content + - Headers and footers + - Code syntax highlighting + - Proper page breaks ## Requirements ### System Requirements -- Python 3.7 or higher +- Python 3.7+ - Git installed and accessible from command line -- Internet connection for repository access +- Internet connection for cloning repositories ### Python Dependencies -Install all required packages: -```bash -pip install -r requirements.txt -``` - -Install Playwright's browser: ```bash +pip install gitpython markdown packaging playwright pyyaml tqdm playwright install chromium ``` -## Installation +## Usage -1. Clone this repository or download the script files: +1. Clone this repository: ```bash -git clone -cd +git clone +cd ``` 2. Install dependencies: @@ -48,116 +42,55 @@ pip install -r requirements.txt playwright install chromium ``` -3. Ensure you have the following files in your directory: - - `astro_docs_to_pdf.py` (main script) - - `requirements.txt` - - `styles.css` (will be created automatically if missing) - -## Usage - -Run the script: +3. Run the script: ```bash python astro_docs_to_pdf.py ``` The script will: -1. Clone/update the Astro documentation repository -2. Process all documentation files -3. Generate a PDF with proper formatting -4. Create a table of contents -5. Output the final PDF as `Astro_Documentation_YYYY-MM-DD.pdf` +- Create a default styles.css if none exists +- Clone the Astro documentation +- Process all documentation files +- Generate a PDF with table of contents ## Output -The generated PDF includes: -- Cover page with title and date -- Table of contents with page numbers -- Formatted documentation content -- Code syntax highlighting -- Properly sized images -- Headers and footers with page numbers -- Consistent styling throughout +The script generates: +- A PDF file named `Astro_Documentation_YYYY-MM-DD.pdf` +- Default styling for documentation content +- Hierarchical table of contents +- Page numbers and generation date -## Customization +## Features -### CSS Styling -The script creates a default `styles.css` file if none exists. You can modify this file to customize the PDF's appearance. +- Automatic table of contents generation +- Code block syntax highlighting +- Image processing +- Proper handling of Astro's MDX format +- Frontmatter parsing +- Clean page breaks +- Responsive design +- Error handling and reporting -### Output Options -You can modify these variables in the script: -```python -repo_dir = "astro-docs" # Local directory for cloned repo -output_pdf = f"Astro_Documentation_{datetime.now().strftime('%Y-%m-%d')}.pdf" # Output filename -``` +## Modifications from Original -### PDF Format -Adjust the PDF format options in the `generate_pdf` function: -```python -format_options = { - 'format': 'A4', - 'margin': { - 'top': '50px', - 'right': '50px', - 'bottom': '50px', - 'left': '50px' - }, - 'print_background': True, - # ... other options -} -``` +This fork includes several modifications from the original Docs-Exporter: +- Updated to use Playwright instead of wkhtmltopdf +- Added support for Astro's specific MDX format +- Enhanced frontmatter parsing +- Improved error handling +- Automatic CSS generation +- Better image handling -## Troubleshooting +## Credits -### Common Issues - -1. **Git Clone Failures** - - Ensure you have git installed - - Check your internet connection - - Verify repository access permissions - -2. **PDF Generation Errors** - - Check if output PDF is already open - - Ensure enough disk space - - Verify Playwright browser installation - -3. **Image Loading Issues** - - Check internet connection - - Verify image paths in documentation - - Ensure Playwright timeouts are sufficient - -4. **Styling Problems** - - Verify styles.css exists and is readable - - Check CSS syntax - - Ensure no conflicting styles - -### Error Messages - -The script provides detailed error messages for common issues: -- Repository cloning failures -- File processing errors -- PDF generation problems -- Resource cleanup issues - -## Limitations - -- Requires active internet connection -- May take several minutes for large documentation sets -- Memory usage scales with documentation size -- Some complex MDX components may not render perfectly - -## Contributing - -Contributions are welcome! Please feel free to: -1. Report bugs -2. Suggest improvements -3. Submit pull requests +- Original project: [Docs-Exporter](https://github.com/Riyooo/Docs-Exporter) by Riyooo +- Modified for Astro documentation format ## License -This project is open source and available under the MIT License. +[Include the original project's license information here] -## Acknowledgments +## Contributing -- Built using Playwright for PDF generation -- Processes documentation from the official Astro docs repository -- Uses Python's markdown library for processing +Contributions are welcome! Please feel free to submit a Pull Request.