83 lines
2.1 KiB
Markdown
83 lines
2.1 KiB
Markdown
|
# PDF Generation Scripts
|
||
|
|
|
||
|
|
This directory contains scripts to generate a professional PDF from the documentation with rendered Mermaid diagrams and working internal links.
|
||
|
|
|
||
|
|
## Files
|
||
|
|
|
||
|
|
- **`Dockerfile`** - Docker container with Mermaid CLI and custom conversion script
|
||
|
|
- **`convert-docs.js`** - Custom Node.js script that handles Mermaid rendering and link fixing
|
||
|
|
- **`build-and-generate-pdf.sh`** - macOS/Linux script
|
||
|
|
|
||
|
|
## Usage
|
||
|
|
|
||
|
|
### Prerequisites
|
||
|
|
- Docker installed and running
|
||
|
|
- Run from the `docs_temp/scripts` directory
|
||
|
|
|
||
|
|
### macOS/Linux
|
||
|
|
```bash
|
||
|
|
cd docs_temp/scripts
|
||
|
|
./build-and-generate-pdf.sh
|
||
|
|
```
|
||
|
|
|
||
|
|
## What the Script Does
|
||
|
|
|
||
|
|
1. **Builds Docker Container** - Creates a container with md-to-pdf and all dependencies
|
||
|
|
2. **Combines Documentation** - Concatenates all markdown files in proper order
|
||
|
|
3. **Adds Page Breaks** - Inserts page breaks between major sections
|
||
|
|
4. **Renders PDF** - Converts markdown to PDF with:
|
||
|
|
- Rendered Mermaid diagrams
|
||
|
|
- Professional styling
|
||
|
|
- Table of contents
|
||
|
|
- Code syntax highlighting
|
||
|
|
- Proper margins and formatting
|
||
|
|
|
||
|
|
## Output
|
||
|
|
|
||
|
|
The script generates a timestamped PDF file:
|
||
|
|
- **Format**: `DoczyAI-Documentation-YYYYMMDD_HHMMSS.pdf`
|
||
|
|
- **Location**: `docs_temp/` directory
|
||
|
|
- **Features**:
|
||
|
|
- Working internal links
|
||
|
|
- Rendered Mermaid diagrams as graphics
|
||
|
|
- Professional formatting
|
||
|
|
- Page breaks between sections
|
||
|
|
|
||
|
|
## Troubleshooting
|
||
|
|
|
||
|
|
### Docker Issues
|
||
|
|
```bash
|
||
|
|
# Check Docker is running
|
||
|
|
docker --version
|
||
|
|
|
||
|
|
# Check for container conflicts
|
||
|
|
docker ps -a | grep doczy-docs-generator
|
||
|
|
docker rm -f doczy-docs-generator # if needed
|
||
|
|
```
|
||
|
|
|
||
|
|
### Permission Issues (Linux/macOS)
|
||
|
|
```bash
|
||
|
|
chmod +x build-and-generate-pdf.sh
|
||
|
|
```
|
||
|
|
|
||
|
|
### Large File Generation
|
||
|
|
The PDF may be several MB due to embedded diagrams and styling. This is normal for comprehensive documentation.
|
||
|
|
|
||
|
|
## Customization
|
||
|
|
|
||
|
|
### PDF Options
|
||
|
|
Edit the `--pdf-options` in the script to customize:
|
||
|
|
- Page size (A4, Letter, etc.)
|
||
|
|
- Margins
|
||
|
|
- Background printing
|
||
|
|
- Print quality
|
||
|
|
|
||
|
|
### Styling
|
||
|
|
Modify the `--css-string` section to change:
|
||
|
|
- Fonts and colors
|
||
|
|
- Table styling
|
||
|
|
- Code block appearance
|
||
|
|
- Header formatting
|
||
|
|
|
||
|
|
### File Order
|
||
|
|
Change the concatenation order in the script to rearrange sections.
|