> [!kanban]+ [[Obsidian TTRPG Tutorials]] / [[Plugin Tutorials]] / [[TTRPG-Convert-CLI]] / [[TTRPG-Convert-CLI 5e]]
> - [[Getting Started]]
> - ![[Pasted image 20230527003751.jpg|hsmall+wsmall+center]]
> - [[Plugin Tutorials]]
> - ![[Pasted image 20230527184201.jpg|hsmall+wsmall+center]]
> - [[Community Supported Games]]
> - ![[Pasted image 20230527001506.jpg|hsmall+wsmall+center]]
> - [[Obsidian TTRPG Tutorials/Templates/Templates\|Templates]]
> - ![[Pasted image 20230530220438.jpg|hsmall+wsmall+center]]
> - [[Community and Support]]
> - ![[Pasted image 20230527005303.jpg|hsmall+wsmall+center]]
> [!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
> [!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.
[Obsidian TTRPG Discord (Join this first)](https://discord.gg/8AF29UBUCa) > [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]]
- [ ] 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
> ````
Navigate to [[TTRPG-Convert-CLI 5e-20240904194144499.webp|this website]].
Download the latest versions of [[TTRPG-Convert-CLI 5e-20240904194345455.webp|these files]].
Create a folder within your `bin` folder called `5etools-mirror-2.github.io`. Extract the contents of the [[TTRPG-Convert-CLI 5e-20240904194918189.webp|highlighted zipped file]] into this folder.
Create a folder within your `bin` folder called `5etools-img`. Extract the contents of the [[TTRPG-Convert-CLI 5e-20240904195048566.webp|highlighted zipped 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`.
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]]