This article walks you through how to create a document for PD Reader. To learn how to add a document, see How to add a document.

PD Reader doesn’t natively read standard document formats (e.g. PDF). Instead, documents must be prepared as a special document folder. A document folder is a folder that contains images, where each image represents a page in your document.

Once you’ve created a document folder, you can zip it up and share it with others! People who download your document won’t need to go through this process again, they can simply drop the document folder on their device and enjoy your content.

Important note: the following requires utilizing the Playdate SDK, which requires some technical knowledge.

Overview

The process for creating a document folder can be summarized in these main steps:

1. Create page images
2. Create a document folder
3. Convert images with the Playdate SDK
4. Copy your document folder to your device

1. Create page images

Images pages are are displayed in alphanumeric order in PD Reader, so name them in the order which you want them to be displayed.

Additionally each page image must be…

• A minimum width of 400 pixels
• A minimum height of 240 pixels
• Black and white
• Exported as a PNG

With these requirements in mind, you have several options for creating image pages.

Create image pages by hand

If you’re creating new content (such as a zine or comic) specifically for consumption on the Playdate, it’s highly recommended that you author your pages by hand in your preferred image editor. This method allows for the most control over how your document will look.

Suggested image editors:

• Paint.NET (free)
• Inkscape (free)
• Aseprite (paid)
• Adobe Photoshop (paid)

Extract image pages from existing documents

If you have existing documents, such as full color PDFs, you can extract image pages using the command-line tool ImageMagick.

Once installed use the following command, where input.pdf is the path to your existing document:

magick convert -resize 400 -threshold 60% -monochrome input.pdf page.png

Brief explanation and recommendations of parameters used above:

• convert: convert between image formats, in our case, from PDF to PNG
• -resize 400: export pages as 400 pixels wide. You can use larger values, but keep in mind your document will then be larger than the Playdate’s screen.
• -threshold 60%: the threshold parameter affects the conversion to monochrome. In my tests 60% was generally the best all around value, but you should play with this number to fine tune your document. See the ImageMagick doc on threshold for more info.
• -monochrome: transform the document to black and white.

ImageMagick has a plethora of other options, so I high recommend exploring the ImageMagick’s docs.

Create image pages from existing PNGs

If you have existing full color PNGs, you can use onebitdithertool to convert them to 1-bit with a variety of dithering options.

2. Create a document folder

Next you’ll create a folder which represents your document folder.

Create a new folder and add all of your images created in step 1. The name of the folder will be used as the in-app document name.

Optional) Add an image named card.png with the dimensions 350 pixels by 155 pixels to use as a custom card in the document list. If not provided, a plain white card with your document name will be shown instead.

Add a new file named main.lua. This file should be empty and is only used when converting images in the next step.

3. Convert images with the Playdate SDK

Next you’ll use the Playdate SDK to convert the images in your document folder to a format that they Playdate can read.

First you’ll need to install the Playdate SDK.

Then compile the folder using the pdc tool by using the following command, and replace “MyDocument” with the name of the folder you created in step 2:

pdc MyDocument MyDocument.pdx

In the compiled document folder (i.e. MyDocument.pdx) delete the main.pdx and pdxinfo files. These files are generated during the compilation process and aren’t needed. However, they won’t cause any problems if they’re not removed.

4. Copy your document folder to your device

Your document is now ready to be viewed on your Playdate! See How to add a document.