ebullient·works

TTRPG convert CLI

GitHub all releases

A Command-Line Interface designed to convert TTRPG data from 5eTools and Pf2eTools into crosslinked, tagged, and formatted markdown optimized for Obsidian.md.

Jump ⬇ Download ⚙️ Configuration 🎨 Examples 🎨 Templates
🚜 Changelog 🗺️ Source Map 📖 5eTools 📖 Pf2eTools 📖 Homebrew

I use Obsidian to keep track of my campaign notes. This project parses JSON sources for materials that I own from the 5etools mirror to create linked and formatted markdown that I can reference in my notes.

Tip

Using the Command Line

This tool works in the command line, which is a text-based way to give instructions to your computer. If you're new to it, we have resources to help you get started below.

If you don't have a favorite method already, or you don't know what those words mean, here are some resources to get you started:

Install the TTRPG Convert CLI

There are several options for running ttrpg-convert. Choose the one you are most comfortable with:

Platform Options
Linux jbang, brew, bin, jar, src
Mac (Arm) brew, jbang, bin, jar, src
Mac (Intel) brew, jbang, bin, jar, src
Windows 📝, jbang, bin, jar, src
Windows (Old) 📝, jbang, jar, src
Windows (WSL) brew, jbang, jar, src

Recommendations for using the CLI

Required Plugins

Conventions

Convert 5eTools JSON data

Note

Instructions here use backslashes to wrap lines for readability (a common practice for Linux-based command shells).

If you are using Windows, you will need to remove the backslashes and put the command on a single line. You may also need to append .exe to the command name (though it should work without).

  1. Invoke the CLI with the --version option.

    ttrpg-convert --version

    You should see output similar to the following:

    ttrpg-convert version 2.3.18
Git commit: ed56f76

    If you do, we know that the CLI is working!

    If you don't, there may be something wrong with your installation. Windows users, see the Windows README for help.

  2. Invoke the CLI to generate indexes and markdown for SRD content:

    ttrpg-convert \
  --index \
  -o dm \
  <5etools-data-dir>

    • --index generates two index files: all-index.json and src-index.json.

      🚀 TIP:

      • Use all-index.json to see the reference keys for all discovered content. This can confirm that an included source was actually read.
      • Use src-index.json to see the reference keys for content that was included in the generated output. Use this to confirm that your source selection is working as expected.

    • -o dm The target output directory (dm in this case). Files will be created in this directory.

    • <5etools-data-dir> is a placeholder for the location of downloaded 5eTools source data directory.

    This should produce a set of markdown files in the dm directory that contains only SRD content.

  3. Next, you'll want to create a configuration file to set up your sources.

    The configuration is provided to the CLI using the -c option:

    ttrpg-convert \
    --index \
    -o dm \
    -c my-config.json \
    <5etools-data-dir>

    🚀 Note: Only include content you own. Find the identifier for your sources in the Source Map.

Next step:

Convert Pf2eTools JSON data

🚜 🚧 🚜 🚧 🚜 🚧 🚜 🚧

Note

Instructions here use backslashes to wrap lines for readability (a common practice for Linux-based command shells).

If you are using Windows, you will need to remove the backslashes and put the command on a single line. You may also need to append .exe to the command name (though it should work without).

  1. Invoke the CLI with the --version option:

    ttrpg-convert --version

    You should see output similar to the following:

    ttrpg-convert version 2.3.18
Git commit: ed56f76

    If you do, we know that the CLI is working!

    If you don't, there may be something wrong with your installation. Windows users, see the Windows README for help.

  2. Invoke the CLI. In this first example, let's generate indexes and markdown for default content:

    ttrpg-convert \
  -g pf2e \
  --index \
  -o dm \
  <Pf2eTools-data-dir>

    • -g pf2e The game system! Pathfinder 2e!

    • --index generates two index files: all-index.json and src-index.json.

      🚀 TIP:

      • Use all-index.json to see the reference keys for all discovered content. This can confirm that an included source was actually read.
      • Use src-index.json to see the reference keys for content that was included in the generated output. Use this to confirm that your source selection is working as expected.

    • -o dm The target output directory. Files will be created in this directory.

    • <Pf2eTools-data-dir> is a placeholder for the location of downloaded 5eTools source data directory.

  3. Next, you'll want to create a configuration file to set up your sources.

    The configuration is provided to the CLI using the -c option:

    ttrpg-convert \
    -g pf2e \
    --index \
    -o dm \
    -c my-config.json
    <Pf2eTools-data-dir>

    🚀 Note: Only include content you own. Find the identifier for your sources in the Source Map.

Next step:

Convert Homebrew JSON data

The CLI tool can also import homebrewed content, though this content must still fit the JSON standards set by the 5eTools JSON spec or the PF2eTools JSON spec (coming soon, similar to 5eTools).

Perhaps the simplest way to import homebrew is to use existing homebrew data from the 5eTools homebrew GitHub repo: https://github.com/TheGiddyLimit/homebrew.

Tip

🍺 You only need the specific file you wish to import.

Homebrew data is different from the 5eTools data. Each homebrew file is a complete reference. If you compare it to cooking: the 5eTools mirror repo is organized by ingredient (all of the carrots, all of the onions, ...); homebrew data is organized by prepared meal / complete recipe.

Adding homebrew content is easiest if you use a configuration file. We will assume a file named my-config.json for the example below, but you can use any name you like.

Important

🚀 Respect copyrights and support content creators; use only the sources you own.

For example, if you want to use Benjamin Huffman's popular homebrewed Pugilist class:

  1. Download a copy of the Pugilist JSON file.

    Save this file to a well-known location on your computer. It is probably easiest if it sits next to your 5eTools or Pf2eTools directory.

  2. Update your configuration file to add a homebrew section under sources:

    {
    "sources": {
        ...
        "homebrew": [
            "path/to/Benjamin Huffman; Pugilist.json"
        ]
    }
}
    • path/to/ is a placeholder for a relative or absolute path to the file[1]. Here are a few ways to determine the path to a file:
      • You may be able to drag and drop the file into the terminal window.
      • You may be able to right-click on the file and select "Copy Path".
      • Windows users: When pasting the path into a text editor, use find/replace to replace all \ with /.

  3. Run the command like so (for 5e homebrew):

    ttrpg-convert \
    --index \
    -o hb-compendium \
    -c my-config.json \
    <5etools-data-dir>
    • -o hb-compendium specifies the output directory for generated content.
    • -c my-config.json specifies the name and/or path to your configuration file.
    • <5etools-data-dir> is a placeholder for the 5eTools source data directory.

See configuration for more details on how to configure the CLI.

The process is similar for other homebrew, including your own, as long as it is broadly compatible with the 5eTools JSON spec.

Where to find help

Want to help fix it?

Other notes

This project uses Quarkus, the Supersonic Subatomic Java Framework. To learn more about Quarkus, please visit its website: https://quarkus.io/.

This project is a derivative of fc5-convert-cli, which focused on working with FightClub5 Compendium XML files. It has also borrowed some bits and pieces from pockets-cli.

Buy Me A Coffee

  1. Description of relative vs absolute file paths: https://stackoverflow.com/a/10288252. If you use a relative path, it will be resolved relative to the current working directory, as described here: https://en.wikipedia.org/wiki/Working_directory. ↩︎