Matthew Ayers

I create my ideas with code.

7 minute read

How To Install Playmaker

Paul Hudson's Playmaker tool is extremely useful for converting regular markdown files into Xcode Playgrounds. This can be used for a number of different purposes, especially learning Swift and providing guided tutorials. To learn more about Playmaker, check out the GitHub page here: Playmaker on GitHub

Once you've had a chance to read about it, you can follow the detailed instructions to install it below.

For information on how to use Playmaker, see the Playmaker GitHub repository or scroll to the bottom of the page for more.


In order to use Playmaker, you will need a Mac with Xcode installed. It is possible to do this on Linux, and the instructions should be mostly the same, but I will focus on this from a Mac user's perspective.

Some familiarity with the macOS Terminal or a command line interface of some sort will help simplify this process.

Prepare to Install

First, please ensure that you have the latest version of Xcode. You can do this through the Mac App Store by typing in "Xcode" and downloading or updating the program. If you already have the latest version of Xcode, you can open up the macOS Terminal app and type in the following command to make sure you have the necessary command line tools to run this program:

xcode-select --install

After typing in this command, press the "Enter" or "Return" key on your keyboard to run the command. It will either prompt you to install the components, tell you that they have already been installed, or give some sort of error. If there is an error, feel free to let me know so I can add troubleshooting tips here.

Downloading Playmaker

After setting up everything related to Xcode, go to this link to install Playmaker:

On that page, find the green "Code" button, click on it, and select the "Download ZIP" option. IMPORTANT: Please save the ZIP file to the Downloads folder on your computer. This will help you with setup and will make it easier to follow along later. For those of you who would like to know the exact path for the download, it should be in ~/Downloads.

When it finishes downloading, double click the ZIP file's icon to extract the contents into a separate directory. Please do not change the name of the ZIP archive or the extracted folder, again to simplify the installation process later on.

Installing Playmaker

Now that we have Playmaker on our computer, we need to prepare the executable so that we can run it on any markdown files we want to convert into playgrounds. This can be a little tricky, so be sure to read everything before completing any part of the instllation.

First, you will need to open up the native macOS Terminal app or your favorite terminal (I prefer iTerm 2). If you would like to make sure that you are in your home directory before we go to the Playmaker files, you can run (by pressing enter/return) ls and you should see directories such as your Desktop, Downloads, Documents, and more. Once you have verified this, run the following command (case-sensitive):

cd Downloads/

Now your terminal should now be in your Downloads directory. This is important because otherwise we will not be able to find the Playmaker directory.

Next, we need to go into the Playmaker directory. To do this, run the following:

cd Playmaker-main/

After running this, verify that you are in the Playmaker directory by running ls. You should see the following items pop up: - Example - LICENSE - Package.swift - - Sources

If you see this, then you have successfully gotten to the Playmaker directory!

Now we need to build Playmaker in order to use it. To do this, simply run (in the Playmaker directory) the following:

swift build

If all goes well, you should see a message like "Build complete! (1.29s)" to indicate that. If it does not finish or there is an error, you may need to restart your computer to fix the issue. If the issue persists after restarting, it could be an issue with Playmaker, your computer, Xcode, or an outdated version of macOS. Feel free to reach out or open an issue on GitHub if you have any trouble.

Finishing Playmaker Setup

Now that Playmaker has been built, we need to move it to a much more useful location on our computer. While you are still in the Playmaker directory, run the following command:

cp .build/debug/playmaker .

This will make a copy of the Playmaker executable file that you created during the installation process in your Playmaker directory. Now that you have the executable, which should simply be called playmaker, you will be able to run it using the following command (in your Playmaker directory):

./playmaker Example/

When you run the above command in the Playmaker directory, it will generate an Xcode Playground file from the markdown files in the Example directory. The output will be contained within that directory if all goes well, so be sure to check in there for a file titled "Example.playground".

In the future, you will be able to run playmaker on any directory containing the proper file structure and following the same format as the command above. To learn more about how to build playgrounds with this installed, please see the Playmaker GitHub repository.

Now that we've tried that out, I want to mention that it can be a bit annoying to have to type in ./ every time we want to run Playmaker, so the next step is an optional way of making it possible to not only run Playmaker without adding ./ , but also to have Playmaker available no matter what directory you are in.

Making Playmaker More Convenient (optional)

*Note: You may not be able to do this if your computer is managed or requires administrative privileges. Please be careful and make sure everything is typed in exactly.*

Now that we have Playmaker, it can be really useful to have available no matter what directory we are in on our computer. In order to make this a reality, we only have one more step to complete. Run the following command, while still in your Playmaker directory with the playmaker executable, to make Playmaker accessible from anywhere on your computer:

cp playmaker /usr/local/bin/playmaker

After running this command, the executable for Playmaker should be accessible no matter what directory you are in. To test this, run the following:

cd ~/Desktop/ && playmaker

This will switch your directory to your Desktop and attempt to run Playmaker from the /usr/local/bin directory. Upon running that command, you should see one of the following messages:

You must have at least one file called Introduction, e.g. "1." or "001.".

Unable to locate any pages. Please create at least one page called "1.".

If you see this, then congrats! You have a fully-functioning installation of Playmaker that you can use anywhere on your computer. For full instructions on how to format markdown files in Playmaker, please see the documentation in or head to the following link: Playmaker on GitHub

How To Use Playmaker

To use Playmaker, build out the markdown files as described in the Playmaker GitHub repository, and when you have your pages built and ready to convert into a playground file, type in the following command one level up from where your markdown files are located. For example, if you have your markdown files in ~/Playgrounds/playground-fun/, you would want to run this command in ~/Playgrounds/. The command you would run, going off of the previous example and assuming you have Playmaker in the proper directory, would be the following:

playmaker playground-fun/

This will create a playground in the directory provided as input, and when you open the playground you will see that all of the files that were markdown files in that directory are now part of the playground. For more guidance on this, please see the following link: Playmaker on GitHub

Tagged with: