> [!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) | > > Tutorials | > ---| > **Step1: [[TTRPG-Convert-CLI 5e\|Setup]]** | > Step2: [[TTRPG-Convert-CLI Config File\|Config File Creation]] | > Step3: [[TTRPG-Convert-CLI Templates\|Templates]] | > Step5: [[TTRPG-Convert-CLI Homebrew Content\|Homebrew Content]] | > Step 6: [[TTRPG-Convert-CLI Custom Content\|Custom Content]] | > Alternative: [TTRPG Convert CLI for MacOS](https://youtu.be/O66n448NG4M) | This process can be used to quickly create notes for the D&D5e content that you own.  ## Official Documentation > [!success] CLI Status > - FUNCTIONAL - This process still works with older sources of data. The process below is updated for v1.210.4. > - 2024 PHB is not currently supported but support is being actively developed. > [!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) > > One of the most common issues is that people have missed either setting up a [Configuration File](https://github.com/ebullient/ttrpg-convert-cli/blob/main/docs/configuration.md) or missed some config from their [Configuration File](https://github.com/ebullient/ttrpg-convert-cli/blob/main/docs/configuration.md) ### 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) ### Process Tracker This is a pretty lengthy process so I have added this checklist you can use to mark off the process as you go. - [ ] Download TTRG-Convert-CLI - [ ] Create Folder for CLI - [ ] Extract TTRG-Convert-CLI to Folder - [ ] Download GIT - [ ] Install GIT - [ ] Download Content - [ ] Create your [[TTRPG-Convert-CLI Config File]] (Note: This is a vital step that people commonly miss) - [ ] Run the CLI - [ ] Copy content into the root folder of your Vault (eg: VaultFolder/Paste Here) - [ ] Restart Vault - [ ] Wait for Index to Complete - [ ] Install Admonitions - [ ] Install Admonitions JSON - [ ] Install Force Note View - [ ] Configure Force Note View - [ ] Install Fantasy Statblocks (Note if you plan on using this plugin you must change the default [[TTRPG-Convert-CLI Templates]]) - [ ] In Fantasy Statblocks settings enable the option to parse monsters from notes.\ - [ ] Install Initiative Tracker (Make sure you enable the option to sync monsters from Fantasy Statblocks in the settings) - [ ] DO NOT MOVE THE CONTENT ### 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 dont 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. `The download is approximately 11.4gb currently` ![[Pasted image 20230820093235.png]] ### Create A Home for TTRPG-Convert-CLI Create a folder where the CLI is going to live. I have put mine in `C:\CLI\5eTools\` 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 20230820093446.png]] ### Install Git Git is an application that allows you to control Github using Command Prompts. 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. **Note:** You can see I have additional folders in my `bin` folder. Do not worry. I have completed the process and therefore you should not expect to see them yet. > [!NOTE]- OLD PROCESS - IGNORE FOR NOW > 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-2/5etools-mirror-2.github.io.git > ```` > Press Enter to commence the process. > > ![[explorer_8Sz2PjwSQu.gif]] > > From here it takes quite a bit of time. Basically the process is downloading a copy of the 5eTools site onto your machine. > > > [!warning]+ OPTIONAL: 5eTools Install Guide > > The 5eTools site can be installed and run locally on your own machine. If you would like to learn more about this you can check the [Install Guide](https://wiki.tercept.net/en/5eTools/InstallGuide). We only need to complete STEP 1 for the Obsidian CLI process which is documented on this page however the link will take you further if you want. > > #### Images > Clone the images into the `bin` folder also. > ```` > git clone --depth 1 https://github.com/5etools-mirror-2/5etools-img.git > ```` Download the zip file from here: https://github.com/5etools-mirror-3/5etools-src/releases/download/v1.210.4/5etools-v1.210.4.zip Download the zip files from here: [Release v1.210.4 · 5etools-mirror-3/5etools-img · GitHub](https://github.com/5etools-mirror-3/5etools-img/releases/tag/v1.210.4) - This is a multi-part zip file. You will need to download all the parts that end with \*.z## and the \*.zip file. - Download them all into the same folder and then open the \*.zip file with your favoured zip application. I use [7-Zip](https://www.7-zip.org/) Create a folder within your `bin` folder called `5etools-mirror-2.github.io`. Extract the contents of the `5etools-v1.210.4.zip` into this folder. Create a folder within your `bin` folder called `5etools-img`. Extract the contents of the multi-part zip file into this folder. Once the process is complete you should see a folder titled `5etools-mirror-2.github.io` inside of your `bin` folder. ![[TTRPG-Convert-CLI 5e-20240904195303101.webp]] ### Run The CLI 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. Type `ttrpg-convert.exe --index -o dm 5etools-mirror-2.github.io/data` and hit `Enter`. Wait for the process to complete. Note that this will only download the 5e SRD. > [!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`. > [!warning] Baby Steps > **NOTE:** This tutorial is designed to step you through and get the tool working. > Default out of the box. The tool will create the SRD notes only. You will need to add a [[TTRPG-Convert-CLI Config File]] to add the content that you own to the process. Importantly, this tutorial ensures the tool is working for you; before you attempt to increase the complexity by adding additional content. So finish this tutorial first so that you know things are working and then move onto more complex configurations. > > **NOTE:** People who try to add absolutely everything almost always end up with a host of errors. > [!warning] Monster Note Format > By default this tool creates Monster notes in a basic Markdown format and does not use the Fantasy Statblock plugin. > If you would like to use Fantasy Statblocks instead you need to change the template being used for the monsters. > You do this in your config file. See: [[TTRPG-Convert-CLI Templates]] 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. ![[Pasted image 20230820100349.png]] ### Move The Files 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. There is an example of that in [[TTRPG Convert CLI - 5e Example]]. 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. ![[Once .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 indended. 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` #### Force Note View This is used to make Obsidian treat the generated notes as `read only`. Install the [Force Note View](obsidian://show-plugin?id=obsidian-view-mode-by-frontmatter) plugin and then configure it. `Obsidian > Settings > Community Plugins > Force Note View > Options > ` `- Ignore force view = Enable` `- Ignore open file = Enable` #### Fantasy Statblocks Some of the CLI templates use the [Fantasy Statblocks](obsidian://show-plugin?id=obsidian-5e-statblocks) plugin so install that. #### Initiative Tracker Some of the CLI templates use the [Initiative Tracker](obsidian://show-plugin?id=initiative-tracker) plugin so install that. #### Install CSS Snippets These snippets are optional but can improve the way the notes look. Download the [code as a zip file]( https://github.com/ebullient/ttrpg-convert-cli/archive/refs/heads/main.zip). This zip file contains some useful templates and css snippets. I have extracted this into the `C:\CLI\5eTools\bin` folder so that I can find them easily in the future. Check inside this folder: `C:\CLI\5eTools\bin\ttrpg-convert-cli-main\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>` ### Advanced Configuration Ok so now that we have successfully used the CLI process... lets break it down to try and understand it a bit. We invoked the CLI with this command. This downloads the 5e SRD content. `ttrpg-convert.exe --index -o dm 5etools-mirror-2.github.io/data` #### Create Index Files `--index` This generates 2x \*.json files as part of the output. Basically files that list all of the ids for the notes that have been created. This can be useful when tweaking exclude and include rules. I have not documented this process however you should check the [Official Read-Me](https://github.com/ebullient/ttrpg-convert-cli) for further details. #### Change The Output Folder `-o dm` This is the output directory. You can change the folder name `dm` to something different if you like. #### Add Additional Sources `-s PHB,DMG,SCAG` Adding this to the command line will add the PHB, DMG and SCAG notes to the process. Only use sources that you own and support content developers. You can find a list of sources [HERE](https://github.com/ebullient/ttrpg-convert-cli/blob/main/docs/sourceMap.md) **Note:** There is a better way to do this. There are links below to creating a config file that replaces this step. > [!tip]- Sources > ## Source name mapping for 5eTools > Support content creators and **only include sources that you own**. > > https://github.com/ebullient/ttrpg-convert-cli/blob/main/docs/sourceMap.md #### Create A Config File Configuration Files are vital to the process. This is where you can define the following: - Sources to include in the process. - Change the templates, if you want to use the [[Fantasy Statblocks]] plugin with the CLI notes, then you need to do this. - Change the folder structure for the CLI notes. - How to handle images. See [[TTRPG-Convert-CLI Config File]] #### Template Support - Change the templates, if you want to use the [[Fantasy Statblocks]] plugin with the CLI notes, then you need to do this. See [[TTRPG-Convert-CLI Templates]] #### Homebrew Content See [[TTRPG-Convert-CLI Homebrew Content]] - Assumes you have made a Config File. #### Enter Custom Content See [[TTRPG-Convert-CLI Custom Content]] - Assumes you have made a Config File. # Example of My Setup Here is an example of how I have the tool setup. This might be useful for visualising how all of this comes together. [[TTRPG Convert CLI - 5e Example]]