Documentation and Guide

Installation

This requires PHP 8.1 or above.

This tool is meant to be part of the repository that you have your written content. Because of that, you can install it into the local directory with the following command.

composer require typesetterio/typesetter-cli

If you want to just use the Typesetter library itself in your project without getting the command line tools, use the following:

composer require typesetterio/typesetter

This documentation focuses on the main functionality - which is using the command line option to generate ebooks. However, most of the configuration and methodology also applies to using the code as a library.

Basic Usage

Before we continue, note that there are two other great resources you may want to also look at.

First, you can look at the core library typesetterio/typesetter. This has the underlying service class and may give you more context. (You don't need to do that, though, if you just want to generate an ebook from your markdown on the command line.)

Second, check out the example project to see one way of setting up a project. While you're there, you can get a free ebook!

Normally, this is meant to be used on the command line. The simplest way to use this would be like this:

vendor/bin/typesetter generate

But that's when everything is set up perfectly. We have some options to configure. Let's dig in.

Initialization

So, you installed it - now what? You can run the init command which will generate some content for you to review and modify.

vendor/bin/typesetter init

Then you'll find a local config.php that contains options for you to change. In addition, you'll receive a folder for your content. You can replace your content there.

Generation

After you've updated your configuration and put in your content, you can generate the book:

vendor/bin/typesetter generate

Boom! You'll find the output PDF directly in the same directory. Now you're done!

Ok now, where do you put your content? Or how do you make your own cover? That's covered next.

Content

You probably want to make an ebook fo your own content and markdown, right? Let's dig in to this.

Cover

There are three options for a cover. The image or the html file should be in the content folder.

First, you can generate a cover image. The file should be named cover.jpg. The default configuration for MPDF is 96dpi. The default page is a A4. This means a standard resolution that fits that is 794 x 1123 (96dpi). You may experiment with different values for larger resolution displays. Remember, the larger in size your image, the larger the resulting PDF may be.

Second, you can generate a cover with HTML. The file should be named cover.html. For more details, reference the HTML processing of MPDF.

Finally, if you do not create either of these, Typesetter will automatically generate a cover page. It will use your title and author configuration options.

Markdown Content

The content folder holds the content that is coupled with your config to create the PDF.

Chapters should be generated in sequentially named files in your content folder. Refer to League Commonmark for more tips on writing and configuring markdown processors. Out of the box there is a pretty good configuration. This includes the following functionality:

• GitHub-flavored markdown
• Attributes
• Spatie's Fenced Code / Indent Code renders

But that's not it. Coming up, check out command line options for generation, config customization to configure your book options, and advanced features.

Command Line Options

By default, the Typesetter generate command will work without any options. However, there are some that you want to use.

Excellent! Let's move on to customizing the configuration of your project.

Config Options

By default, the configuration used during generation is a config.php file in the local directory. You can customize this with command line options if you wish. If you're using the Typesetter library directly and without the CLI, these configuration options reflect the keys of the configuration array.

Config File Format

The configuration file should return an array from PHP. You may have other functionality in it as well (it is require'd during the processing of the command). It's recommended to use full namespaced class names when creating this file as the internal namespace may change as the project progresses.

Creating Config Directly for the Library

Unless you're using the Typesetter functionality as a library, you can skip ahead.

Create a config array and pass that to the config maker. Then create a new instance of the Typesetter class. Call the generate method with your config to get a PDF binary return from MPDF.

Here is an example:

$config = [
    'title' => 'Benjamin Button',
    'observers' => [
        new \Typesetterio\Typesetter\Observers\DefaultMarkdownConfiguration(),
    ],
];
$service = new \Typesetterio\Typesetter\Typesetter(
    new \Typsetterio\Typesetter\Config($config)
);
$pdfContent = $service->generate($config);

You can customize any of the functionality that you normally can in the config.php file directly in that array. Note that you must build the configuration option as detailed above in order to use the service.

Options and Descriptions

Whether you're using the command line or Typesetter as a library, you have the following options to customize:

You're all set. But, we're not done yet! Let's move on to the advanced section.

Advanced

In this section, more advanced usage and configuration is covered.

Observers

Observers allow a decorator or visitor style of design pattern to interact with the process of generating this PDF. To make things as transparent as possible, some core items of the service are even configured in observers.

Observers must implement the Typesetterio\Typesetter\Contracts\Observer interface. You may extend the Typesetterio\Typesetter\Observers\Observer abstract class so you don't have to define every interface method. Then, you can override only the ones you want.

Observers are ran in the order they are registered.

Available observer methods available are the following:

The following Observers are available for you. They should all be prefixed by Typestetterio\Typesetter\Observers:

Chapter

The Typesetterio\Typesetter\Chapter class contains the content of your markdown for that specific chapter.

It contains a number of useful methods for you to interact with the content while it is being converted.

If you'd like to just get some status updates or notifications and don't need to modify any content, check out Events.

Events

During the process of conversion, Typesetter issues some events that you may listen to. This can be useful for giving status updates or creating logs.

In order to register a listener, call the listen method with an event class and a callable.

Here's an example:

$service = new \Typesetterio\Typesetter\Typesetter();
$service->listen(\Typesetterio\Typesetter\Events\Finished::class, function () use ($myNotifier) {
    $myNotifier->alert('The process has finished');
});

At this time events do not contain any data. If you want to modify anything, please look at observers.

The following events are available (these are all going to be in the Typesetterio\Typesetter\Events namespace):

You may listen to as many or as little events as you want. Remember, some of these are optional events based on your configuration.

Themes

Theming support is done with HTML and CSS. The theme folder should contain a theme.html which contains a <style> declaration as if it were in the head of an HTML file. This is where you can customize the theme of your PDF. Remember that you will be working with print styles in CSS so you can use things like page break.

More to come here!

Fonts

At this time, Typesetter only supports the fonts that MPDF does. It will support font management in the future.

To see the list of fonts that are available, see the MPDF Fonts Directory.