Creating PDF and EPUB eBook from Laravel Documentation using Ibis Next
Tags: laravel, documentation, books, tutorial
Published: 2024-05-26 21:57:36

In this article, I will guide you through **creating a PDF and EPUB e-book** from the **Laravel documentation**.
We will use the Ibis Next tool to accomplish this.
The Laravel documentation is available in Markdown format on GitHub, and Ibis Next is a powerful utility for generating eBooks from Markdown files.

## Installing Ibis Next
You must install Ibis Next globally on your machine to create PDF or EPUB files from Markdown files. Ibis Next is a PHP package, so you'll need Composer to install it. If you don't have Composer installed, download and install it from getcomposer.org.

Once Composer is installed, run the following command to install Ibis Next globally:

```shell
composer global require hi-folks/ibis-next
```

Ensure Composer's global `bin` directory is in your system's `PATH`. You can typically add it by adding the following line to your `~/.bashrc`, `~/.zshrc`, or `~/.profile` file:

```shell
export PATH="$PATH:$HOME/.composer/vendor/bin"
```

## Cloning the Laravel Documentation Repository
Then, you need to clone the Laravel documentation repository to your local machine. In your terminal, in a new empty directory, execute the following command:

```shell
git clone --depth 1 https://github.com/laravel/docs.git
```

This command will download the repository containing the Markdown files for the Laravel documentation.

This command will generate the `docs` directory.

## Configure Ibis Next

Ibis Next provides the `init` command that generates the needed configuration and the basic assets files:

```shell
ibis-next init
```

The `init` command will generate the `assets` directory with some assets files, such as the CSS for creating the HTML files and the cover image. It will also generate the configuration file, `ibis.php`.

## Creating the cover (optional)
If you want, you can create the cover image, a PNG or WebP file with the aspect ratio of an A4 file. Or, if you prefer, you can download a basic one like : 

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/vbtqv2fs6vpkjosnnleg.png)

You can save it into `assets/cover-laravel.png`.

## Creating the configuration

Before executing Ibis Next you have to configure it via the `ibis.php` file.
I already prepared a configuration file for setting the page header, the cover, and the list of the proper files. Feel free to override the ibis.php file with this one (and eventually adjust it according to your needs):

```php
<?php

return [
    /**
     * The book title.
     */
    'title' => 'Laravel Doc e-book',

    /**
     * The author name.
     */
    'author' => '',

    /**
     * The list of fonts to be used in the different themes.
     */
    'fonts' => [
        //        'calibri' => 'Calibri-Regular.ttf',
        //        'times' => 'times-regular.ttf',
    ],

    /**
     * Document Dimensions.
     */
    'document' => [
        'format' => [210, 297],
        'margin_left' => 27,
        'margin_right' => 27,
        'margin_bottom' => 14,
        'margin_top' => 14,
    ],

    /**
     * Table of Contents Levels
     */
    'toc_levels' => [
        'H1' => 0,
        'H2' => 1,
        'H3' => 2,
    ],

    /**
     * Cover photo position and dimensions
     */
    'cover' => [
        'position' => 'position: absolute; left:0; right: 0; top: -.2; bottom: 0;',
        'dimensions' => 'width: 210mm; height: 297mm; margin: 0;',
        'image' => 'cover-laravel.png',
    ],

    /**
     * Page ranges to be used with the sample command.
     */
    'sample' => [
        [1, 7],
        [15, 15],
    ],

    /**
     * default commonmark
     */
    'configure_commonmark' => [
    ],
    /**
     * A notice printed at the final page of a generated sample.
     */
    'sample_notice' => 'This is a sample',

    /**
     * CSS inline style for the page header.
     * If you want to skip header, comment the line
     */
    'header' => 'font-style: italic; text-align: right; border-bottom: solid 1px #808080;',

    /**
     * List of the Markdown files.
     * If the `md_file_list` is not set (default)
     * all the markdown files in the content directory
     * will be loaded.
     * If you need to select a subset of markdown files
     * for creating PDF or EPUB or HTML you can list here
     * the files. You need to set the filename in the
     * content directory. The fieldname should include the
     * extension.
     */

        'md_file_list' => [
    'releases.md',
    'upgrade.md',
    'contributions.md',
    'installation.md',
    'configuration.md',
    'structure.md',
    'frontend.md',
    'starter-kits.md',
    'deployment.md',
    'lifecycle.md',
    'container.md',
    'providers.md',
    'facades.md',
    'routing.md',
    'middleware.md',
    'csrf.md',
    'controllers.md',
    'requests.md',
    'responses.md',
    'views.md',
    'blade.md',
    'vite.md',
    'urls.md',
    'session.md',
    'validation.md',
    'errors.md',
    'logging.md',
    'artisan.md',
    'broadcasting.md',
    'cache.md',
    'collections.md',
    'context.md',
    'contracts.md',
    'events.md',
    'filesystem.md',
    'helpers.md',
    'http-client.md',
    'localization.md',
    'mail.md',
    'notifications.md',
    'packages.md',
    'processes.md',
    'queues.md',
    'rate-limiting.md',
    'strings.md',
    'scheduling.md',
    'authentication.md',
    'authorization.md',
    'verification.md',
    'encryption.md',
    'hashing.md',
    'passwords.md',
    'database.md',
    'queries.md',
    'pagination.md',
    'migrations.md',
    'seeding.md',
    'redis.md',
    'eloquent.md',
    'eloquent-relationships.md',
    'eloquent-collections.md',
    'eloquent-mutators.md',
    'eloquent-resources.md',
    'eloquent-serialization.md',
    'eloquent-factories.md',
    'testing.md',
    'http-tests.md',
    'console-tests.md',
    'dusk.md',
    'database-testing.md',
    'mocking.md',
    'billing.md',
    'cashier-paddle.md',
    'dusk.md',
    'envoy.md',
    'fortify.md',
    'folio.md',
    'homestead.md',
    'horizon.md',
    'mix.md',
    'octane.md',
    'passport.md',
    'pennant.md',
    'pint.md',
    'precognition.md',
    'prompts.md',
    'pulse.md',
    'reverb.md',
    'sail.md',
    'sanctum.md',
    'scout.md',
    'socialite.md',
    'telescope.md',
    'valet.md'

        ],

];

```

I also prepared a Gist file, in case you prefer to use Gist: https://gist.github.com/roberto-butti/5e43c07921eefe0a913ab076cb95bc5e

## Generating the PDF file
Now, finally, you have Ibis Next installed and configured so that you can run it. To generate the PDF file using the Laravel cloned markdown files:

```shell
ibis-next pdf --content=docs
```

The file by default will be generated into the `export` directory.
You can open the generated PDF file with your PDF viewer.

## Generating the EPUB file
To generate the EPUB file using the Laravel cloned markdown files:

```shell
ibis-next epub --content=docs
```

The file, by default, will be generated into the `export` directory.
You can open the generated EPUB file with your EPUB viewer or transfer it to your eBook reader device.

> Both commands take a while to complete; the Laravel Documentation is huge, and you will probably create a PDF file with more than 2000 pages!!!

## Customize your PDF or EPUB file
If you want to customize the PDF or the EPUB file, you can read the documentation of Ibis Next here: https://github.com/Hi-Folks/ibis-next

## References
Feel free to drop your comments or feedback below. Some useful references if you want to explore more:
- Ibis Next project: https://github.com/Hi-Folks/ibis-next
- Ibis https://github.com/themsaid/ibis was the original project (now outdated) created by Mohamed. I forked the Ibis project to create Ibis Next to update it with the latest PHP versions and dependencies and add new functionalities like exporting into EPUB format, setting the page headers, etc
- Laravel documentation: https://github.com/laravel/docs