The first framework for fast and easy PDF layout.
Explore ASAP PDF docs »
ASAP PDF is designed to create PDF files using HTML and CSS (Pug/SCSS).
With ASAP PDF, you can:
- Convert HTML to PDF on the fly;
- Get an in-browser preview that’s nearly identical to the final PDF file;
- Inline all external assets to your HTML without using third-party services (your images and fonts are encoded with
base64, and styles are automatically inserted into the
<head>tag); - Use ready-made text components;
- Reuse your components with Pug;
- Stop worrying about stylelint or pug-lint config, as they are already configured;
- Perform screenshot testing of your project and get a detailed report.
Node v14.15.0 or higher
- Download the ASAP PDF repository;
-
In the project root folder, run
npm i; -
To start the project:
-
Run
npm startif you need to inline all external assets to HTML and convert the final HTML to PDF on the fly. The final PDFs will be saved in the folder/dist/pdf/. You can open these PDFs in your IDE to see the result of code changes immediately; -
Run
npm run devif you don't need to inline all external assets to HTML and convert the final HTML to PDF on the fly. Sourcemaps are available in this mode; -
The project will start at
http://localhost:3004/index.html;
-
Run
-
Make a copy of the file
/app/pug/pages/index.pug(or/app/html/html-example.htmlif you want to use HTML) and name it whatever you need; -
Create a SCSS file for the new page in the folder
/app/scss/pages/and import it in the file/app/scss/_pages.scss, if needed; -
Write markup in the file created in step 4. All the code should be written inside the block with
.sheet.A4-m-15mmclasses; - Use ready-made utilities and components;
-
The compiled project files will be saved in the
/dist/folder.
View documentation to learn more about using ASAP PDF.
ℹ️ You can choose HTML files to be converted to PDF on the fly to speed up the process:
- Make a copy of
gulp/config/html2pdfConfig.default.jsand name ithtml2pdfConfig.js. The file must be stored in the same folder ashtml2pdfConfig.default.js;- In
html2pdfConfig.js, set theconvertAllparameter tofalseand specify the list of required pages in thepageListarray.
| Command | Description |
|---|---|
npm start |
Running the project in production mode (on the fly: resources are encoded in Base64 and inserted into HTML, HTML is converted to PDF) |
npm run prod:mock-pdf |
Same as npm start + data mocking (string substitution into labels like {{example}}) |
npm run dev |
Running the project in development mode (resources are not Base64 encoded or inlined, sourcemaps are available) |
npm run test:init |
Creating golden images from a PDF and page golden screenshots. The project must be run with an HTML to PDF converter (such as npm start or npm run prod:mock-pdf) in a separate terminal or in a separate tab of the terminal. |
npm test |
- Screenshot testing - pdf2img testing The project must be run with an HTML to PDF converter (such as npm start or npm run prod:mock-pdf) in a separate terminal or in a separate tab of the terminal. Golden screenshots and images must be created before testing (npm run test:init).- To run the npm test script, you need to install the Poppler library;- Settings for screenshot and pdf testing are stored in the gulp/config/test/ folder. |
npm run test:refresh |
- Replacing old golden screenshots with new ones - Replacing old PDF golden images with new ones - Cleaning up folders with actual screenshots and PDF images |
Check a detailed description of other scripts on the npm scripts page.
You can learn more about testing in ASAP PDF by going to the "About testing" documentation page.
-
app/fonts/
Font files -
app/img/
All images used in the project -
app/js/
JS files of the project -
app/libs/
All libraries and plugins (js/css) used in the project -
app/pug/pages/
Project pages (pug) -
app/pug/templates/
Pug templates (general page structure, header, footer, etc.) -
app/pug/mixins/
Pug mixins -
app/html/
Project pages (html) -
app/scss/
Style files -
temp/
Temporary files (generated in production mode) -
gulp/config
Project settings files -
mocks/
Mocks in json -
tests/screenshots/
Screenshot directory (screenshot testing) -
tests/pdf2img/
Directory for images extracted from PDF (pdf2img testing) -
tests/Screenshot test report.html
Screenshot testing report -
tests/PDF test report.html
pdf2img testing report