> [!column|flex no-title] >> [!menu-dark-red|ttl-c] [[Obsidian TTRPG Tutorials]] > [!column|4 no-title] >> [!menu-green-1|ttl-c] [[Getting Started]] > >> [!menu-green-2|ttl-c] [[Plugin Tutorials]] > >> [!menu-green-3|ttl-c] [[Community Supported Games]] > >> [!menu-green-4|ttl-c] [[Obsidian TTRPG Tutorials/Templates/Templates\|Templates]] > [!column|3 no-title] >> [!patreon|ttl-c] [Patreon](https://www.patreon.com/JPlunkett) ([Starter Vault](https://www.patreon.com/posts/obsidian-patreon-96801399)) > >> [!discord|ttl-c] [Obsidian TTRPG Community Discord](https://discord.gg/CdM9UCJdwU) > >> [!discord|ttl-c] [Obsidian Official Discord](https://discord.gg/8AF29UBUCa) > [!infobox] > # ttrpg-convert-cli > ![[TTRPG-Convert-CLI 5e-20240203092033415.webp|cover hsmall]] > > Links | > ---| > ⚙️[Github Site](https://github.com/ebullient/ttrpg-convert-cli) | > 📄[Official Documentation](https://github.com/ebullient/ttrpg-convert-cli/blob/main/README.md)) | > 🗺️[Source Map](https://github.com/ebullient/ttrpg-convert-cli/blob/main/docs/sourceMap.md#source-name-mapping-for-5etools)) | > 🆘[Support](https://discord.com/channels/925322340995313686/1118630475313975367) 🐛[Raise Issue](https://github.com/ebullient/ttrpg-convert-cli/issues) | > 🍵[Support Ebulient with Coffee](https://www.buymeacoffee.com/ebullient) | > This process can be used to quickly create notes for the D&D5e content that you own. It will create a note per monster, spell, item and even the adventures and rule books! ## Official Documentation > [!success] CLI Status > - FUNCTIONAL - CLI 3.0 has been released which supports 2014 and 2024 content. > - The process below is updated for CLI 3.0 > - The process below will only work on Windows machines. **It WILL NOT work on MACS**. > - Other OS users should check the [official documentation](https://github.com/ebullient/ttrpg-convert-cli) for other methods. > - Check the [OFFICIAL DOCUMENTATION](https://github.com/ebullient/ttrpg-convert-cli) for offical instructions. > - We all benefit from Ebulient's amazing work so consider [Supporting Ebulient with Coffee](https://www.buymeacoffee.com/ebullient) --- > [!danger]+ Solid Advice > The official documentation for this tool will always be the most relevant and updated instructions. While my videos can be helpful; always be aware that the tool updates more than the videos, if something isn't working; check the [OFFICIAL DOCUMENTATION](https://github.com/ebullient/ttrpg-convert-cli) ## Support For support with the CLI system these are the best places to look. Join the Obsidian TTRPG Community Discord using the link in the top menu of this page > [Generic CLI Discussion](https://discord.com/channels/925322340995313686/1118630475313975367) ## Download the Latest Release of TTRPG-Convert-CLI I use Windows and therefore this tutorial is focussed on how to do the process using Windows. I don't have access to Linux or Apple. You can find the latest release here: https://github.com/ebullient/ttrpg-convert-cli/releases Find the latest release and scroll down to the section titled Assets. This is a list of files included in this release. As I am using Windows, I download the one with Windows in the file name. ![[Pasted image 20250127184047.png]] ## Create A Home for TTRPG-Convert-CLI Create a folder where the CLI is going to live. I have put mine in `D:\CLI\` Inside this folder you need to extract the contents of the \*.zip we downloaded in the step above. The result should look like this. ![[Pasted image 20250127195643.png]] ## Install Git Git is an application that allows you to control Github using Command Prompts. It's a pre-requisite for the next steps in the process. Download Git from this site and complete the install. https://git-scm.com/downloads ## Download The Content You Intend To Use ### D&D 5e Open the folder you made above and navigate to the `bin` folder. Click in the `Address Bar` and type `cmd` and press `Enter`. This will open the Command Prompt from this location. This is an important step as the next process must be run from the folder where you want to download the site. Paste this into the Command Prompt. You can do this by Right-Clicking on the Command Prompt Window. ``` git clone --depth 1 https://github.com/5etools-mirror-3/5etools-src ``` Press Enter to commence the process. ![[explorer_mk6sSKsefH.gif]] Wait for the process to complete. Basically the process is downloading a copy of the 5eTools site onto your machine. Repeat the same process as above. But this time paste this command. This command will download a copy of the images to your machine. This is a much larger download and may take quite a bit of time if you have a slow internet connection. ``` git clone --depth 1 https://github.com/5etools-mirror-3/5etools-img ``` ## Install the Templates Templates can be used to change the output of the CLI tool. I don't recommend changing these until you get more comfortable with the process. However if you want to use the [[Fantasy Statblocks]] plugin; you will need to change the default template to the one that supports Fantasy Statblocks. Navigate to the ttrpg-convert-cli release page: https://github.com/ebullient/ttrpg-convert-cli/releases/ Download the examples file. ![[Pasted image 20250127191445.png]] Export the \*.zip file into your BIN folder. It should look like this. ![[Pasted image 20250127191649.png]] ## Create Your Config File ==Configuration Files are now a requirement for using the CLI tool.== Create a new Text Document in your BIN folder and rename it to `config.5e.easy.json`. Paste the following into that file and save it. ``` { "sources": { "adventure": [ "LMoP", "LoX" ], "book": [ "XPHB", "XDMG", "XMM" ], "reference": [ "SCREEN" ] }, "paths": { "rules": "3-Mechanics/CLI/rules/", "compendium": "3-Mechanics/CLI/" }, "images": { "copyInternal": true, "copyExternal": true, "internalRoot": "5etools-img" }, "reprintBehavior": "newest", "useDiceRoller": false, "tagPrefix": "ttrpg-cli", "template": { "background": "examples/templates/tools5e/images-background2md.txt", "monster": "examples/templates/tools5e/monster2md-yamlStatblock-body.txt", "item" : "examples/templates/tools5e/images-item2md.txt", "race" : "examples/templates/tools5e/images-race2md.txt", "spell" : "examples/templates/tools5e/images-spell2md.txt" } } ``` > [!IMPORTANT]+ Common Issue - File Type > Make sure you actually change the file type to a json file! Lots of people have common file extensions hidden in Windows and many people have incorrectly renamed the file to `config.5e.easy.json.txt` which causes the process to fail. > >It shou ld look like this. >![[Pasted image 20250127185945.png]] > [!IMPORTANT] Common Issue - Over Doing The Content > Once a month I see someone join our community and dive straight into the CLI tool. They "own" all the content available and thus they add every single item to the Config File looking to create the most amount of notes in the shortest possible amount of time. > Within the hour, they start posting about all the errors they are getting and asking for help. > **Don't do this.** > Start small, prove that you have the tool configured correctly. Make sure it runs! **Then start adding the content that you need to run your campaign**. > You do not need every single adventure in your vault. Trust me, this will cause you issue. It will slow down Obsidian and linking will become a nightmare. > > **Not all content on 5eT is equal!** > Some of the content is created by official helpers. They ensure the data files follow the rules. > Some of the content is created by the community. There's a higher chance they did not follow the rules. > If the rules aren't followed, the CLI tool may not work. As such you are going to have more success with the official modules vs 3rd party modules. If it's something that isn't commonly used by lots of people, the chance of errors increases. The process is only as perfect as the data entry. > If you add all of the available content, you will likely start to hit some of these issues. ### Understanding the Config File You can find excellent documentation on the config file here: https://github.com/ebullient/ttrpg-convert-cli/blob/main/docs/configuration.md The documentation covers a lot more than I do and is recommended reading for all users of the CLI tool. #### Adding The Content You Own The content available through this process is documented in the [Source Map](https://github.com/ebullient/ttrpg-convert-cli/blob/main/docs/sourceMap.md) To add content you own, lookup the content in the [Source Map](https://github.com/ebullient/ttrpg-convert-cli/blob/main/docs/sourceMap.md) and take note of the Type field. Copy the Abbreviation for the content into the correct Type section in the config file. Take note of the structure of this information. The commas are important. You need a comma at the end of every line except the last one in each grouping. ![[Pasted image 20250127192339.png]] Here's an example where I have added additional content. Note there is no comma on the end of each section but all content codes above the end; do have a comma. The tool will fail if you have incorrect syntax. ![[Pasted image 20250127192650.png]] #### Set The Home Vault Location This is where you can define the folder where the CLI will go in your vault. You set the location in your config file, and then copy the notes into this location in your vault. This is very important. **DO NOT MOVE THE CLI CONTENT FROM THIS LOCATION** If you want to change the location where the notes go, you need to update your config and re-run the process. This will recreate all of the notes and update the links accordingly. ![[Pasted image 20250127193015.png]] #### How Will Images Be Handled? This section defines how images are handled. - if copyInternal is set to true, it will use images from the internalRoot setting. The setting in the internalRoot needs to match the name of the folder we created above that contains the images. - If copyExternal is set to true, it will download any images that are not available locally. Homebrew content commonly stores images in lots of different places so you will need to set this to true if you are using Homebrew content. ![[Pasted image 20250127193359.png]] #### Dice Roller? My personal preference is to not use Dice Roller in my statblocks. I've found it to be buggy and I don't like that it changes the HP of my monsters everytime I access the note. #### Templates Out of the box, the CLI tool comes with a variety of templates that can be used to change the way the notes look when created. By default, monsters are created as standard Markdown notes. This means they do not use the [[Fantasy Statblocks]] plugin. Most people I encounter though, wish to use [[Fantasy Statblocks]] and as such they need to change the default template that is used to create monsters. We do this in the config file by selecting the template that has `yamlStatblock-body` in the name. In the Template section you need to define the name of the templates you wish to use for each category you wish to control. The path in the config file needs to match what you have in your bin folder exactly. ![[Pasted image 20250127193739.png]] ![[explorer_yQHZOxKrtB.gif]] The example config provided above will create monsters that use the [[Fantasy Statblocks]] plugin. | Format | Template Name | Pros | Cons | | ------------------ | --------------------------------- | --------------------------------------------------------------------------------------------- | --------------------- | | Markdown | object2md-yamlStatblock-body.txt | Very usable<br>Less system intensive<br>Can be published | | | Fantasy Statblocks | monster2md-yamlStatblock-body.txt | Very pretty<br>Cannot be published<br>Includes buttons to trigger comat in Initiative Tracker | More system intensive | | | | | | There are options to store the monster content in the header or body of the note. I personally find the header takes up too much space in the Properties of the note and thus recommend the body version. There are templates for different item types. For now, just know that they are there. It is possible to change them, but that's a tutorial for a later time. ## Are You Ready? By now, your `bin` folder should look like this. If it doesn't; go back up and repeat the process to see what you are missing. ![[Pasted image 20250127200029.png]] ## Run The CLI Navigate to the `bin` folder. Click in the `Address Bar` and type `cmd` and press `Enter`. This will open the Command Prompt from this location. Type the command below in and hit `Enter` (Note: if you copy the command, you can right click to paste it into the command window).  `ttrpg-convert.exe --index -o dm -c config.5e.easy.json 5etools-src/data`  Wait for the process to complete. > [!warning]+ What's Happening? > The CLI process is now running. It is converting the site you downloaded above into Markdown format and putting the notes in a new folder called `dm`. You can tell the process is complete when the command link prompt displays the folder path again. It should provide a summary of the notes that have been created. The created notes will be in the folder called `dm`. ![[explorer_TKCo3WSMM0.gif]] ### Common Errors **Error parsing configuration file (config.5e.easy.json): Unexpected character ('"' (code 34)): was expecting comma to separate Object entries** - There is an error in your config file. Go back through and make sure the Syntax is correct. Are you missing a comma or perhaps have an extra one? ![[Pasted image 20250127214151.png]] - This is a rare error but indicates that your PC is not compatible with the Windows CLI process. If you see this you will need to try a different process such as the Java JAR process. You can find instructions for other methods [HERE](https://github.com/ebullient/ttrpg-convert-cli). The screenshot above shows the error. The JAR file has then been downloaded per the JAR process and the command is then run using the variation shown in the screenshot. ## Copy The Files Into Your Vault Once the process is complete you can find the files inside the `dm` folder. You can now Copy and Paste these into your Obsidian vault. **IMPORTANT:** The folder and files MUST be pasted into your Parent Vault Folder. Do not put them into a sub-folder. Do not rename them. Do not move them. If you do not like the location of the notes within your vault you will need to modify the directory you want them in; in the config file. You should consider the CLI notes as **Read Only**. You will more than likely want to refresh these notes as some point, like when you purchase a new book; and therefore any manual changes you make, would be lost in the refresh process. ![[explorer_Fhscj150b5.gif]] You can now restart your Obsidian Vault. Obsidian will likely need some time to `Index` the new files. ![[Pasted image 20230820101035.png]] ## Setup Your Vault The notes are designed to use some additional elements such as plugins and \*.css files. Work through the steps below to ensure your vault is setup to use the new notes. ### Admonitions Install the [Admonitions Plugin](obsidian://show-plugin?id=obsidian-admonition). This plugin will enable some of the notes to display as intended. Now download the Admonition json files that you would like to use. [admonitions-5e.json](https://github.com/ebullient/ttrpg-convert-cli/tree/main/examples/admonitions) for 5e tools [other-admonitions.json](https://github.com/ebullient/ttrpg-convert-cli/tree/main/examples/admonitions) some additional css files that may be of interest. Save these files to your computer and then install them into the Admonitions plugin. `Obsidian > Settings > Community Plugins > Admonition > Options > Import Admonition(s) > Select Downloaded JSON file` ### Fantasy Statblocks Some of the CLI templates use the [Fantasy Statblocks](obsidian://show-plugin?id=obsidian-5e-statblocks) plugin so install that and then configure it. Obsidian > Settings > Fantasy Statblocks > Note Parsing > Automatically Parse Frontmatter for Creatures = Enabled Obsidian > Settings > Fantasy Statblocks > Note Parsing > Bestiary Folder = Your CLI Folder **Note:** We define the CLI folder here so that it limits where the plugin will search for new monsters. This will speed up the time it takes to start Obsidian. If you leave it with just `/` it will scan your whole vault everytime Obsidian starts. ### Initiative Tracker (Optional) Some of the CLI templates use the [Initiative Tracker](obsidian://show-plugin?id=initiative-tracker) plugin so install that. Obsidian > Settings > Initiative Tracker > Plugin Integrations > Sync Monsters from TTRPG Statblocks = Enabled ### Install CSS Snippets These snippets are optional but can improve the way the notes look. Check inside this folder: `bin\examples\css-snippets` And you should find a number of \*.css files. Copy the ones you would like to use into your vault and then enable them ([[How To - Install Custom CSS]]) from `Obsidian > Settings > Appearance > CSS Snippets > Enable` `Vault\.obsidian\snippets\<copy here>` ## A Note On Best Practice The CLI tool is designed to be run as a blob. It will create interlinked notes that links content between the content that is included in the blob. Thus, you should always run it as a blob. Don't run just one adventure on it's own, because then none of the links to the Player Hand Book will work. You need to include the Player Hand Book in the blob for those links to be made. Once the blob has run, it goes in your vault and you should not move or change those notes. - if you move the notes, it will break any linking that is contained within code blocks. Pictures on the statblocks for example will break. - if you make a change to a note in the CLI blob and in the future want to add a new book to the blob, you won't be able to easily update your content without over-riding the changes you made. Therefore, if you want to make a custom monster, copy a monster note from the CLI but move it somewhere outside of the CLI folder. This way you can change the note as much as you like with no future risk of over riding that note. If you create a new folder outside of the CLI folder for new monsters though, don't forget to add that folder to the Fantasy Statblocks settings so that the plugin knows to parse that folder. **Congratulations... you made it!** ## Updating The CLI Data For Future Runs You will likely want to re-run the CLI tool at some point. The instructions below can be used to update the data so you can re-run the process. #### Update The 5eT Data Navigate to your `bin/5etools-src` folder. Click in the `Address Bar` and type `cmd` and press `Enter`. This will open the Command Prompt from this location. Type: `bit pull` and press enter. This will update to the latest release. #### Update The 5eT Images Navigate to your `bin/5etools-img` folder. Click in the `Address Bar` and type `cmd` and press `Enter`. This will open the Command Prompt from this location. Type: `bit pull` and press enter. This will update to the latest release. #### Update the CLI Executable Navigate to the [ttrpg-convert-cli/releases](https://github.com/ebullient/ttrpg-convert-cli/releases) page and check for the latest release (do not use the Pre-release unless you know what you are doing). Download the latest windows release (ttrpg-convert-cli-X.X.X-windows-x86_64.zip). Export the downloaded zip file and copy the `ttrpg-convert.exe` into your `bin` folder. This will over-ride the old version. #### Make Changes To Your Config File Assuming the reason you want to re-run the process is there's a new book you would like to add to your vault; don't forget to add the book to your config file. #### Rerun the CLI Go back to [[TTRPG-Convert-CLI 5e#Are You Ready?]] and re-run the CLI command.