# Using Obsidian This guide is NOT for using [ObsidianPortal](https://www.obsidianportal.com) for hosting campaigns. This is a gamemaster's guide for installing and using the [Obsidian.md](https://obsidian.md) markdown app for tabletop roleplaying games, campaign management, and running game sessions. These two apps are very different. Obsidian is a FREE private and flexible markdown personal knowledge management (PKM) application that you can adapt to play and manage tabletop roleplaying games (TTRPGs) and campaigns. Obsidian stores notes, syncing them across your devices so you can access them quickly, even offline. No one else can read them; however, you can choose to publish select notes to the web so your players can access campaign-related content. ## Why Use Obsidian? At its core, Obsidian is a simple markdown editor and is not specifically designed for roleplaying games. However, its array of powerful plugins offers a great deal more than other PKM apps of its kind. With these plugins, Obsidian users can add project management features like calendars, databases, day planners, diagrams, interlinked documents, kanban boards, journals, ledgers, lists, outlines, PDF annotation, podcasts, tables, task lists, timelines, whiteboards, wikis, and much more! However, gamemasters can also install RPG-related plugins for 3D dice rolling, fantasy calendars, initiative tracking, name generators, advanced statblocks, and mapping with linkable pins, just for starters. You can also import all your 5E-based RPG materials into an Obsidian vault for instant access, linking, and note-taking needs. Create your own rules companion and run adventures all from one app. The trick is to convert your content to the markdown format; we'll cover that later. The biggest reason to use "markdown" is to ensure future-proofing across all your content against proprietary formats and having to migrate your content from app to app. Your material will forever be easily accessible with Obsidian and almost any markdown or text editor. For RPG support in Obsidian, join the Obsidian community using this [Discord Invite](https://discord.gg/8AF29UBUCa), then visit the [tabletop-games](https://discord.com/channels/686053708261228577/916477002909876265) channel. # Obsidian For Campaigns To begin using Obsidian for your campaign management, follow the steps below. Please read everything; otherwise, you'll miss something vital. ## Step 1: Create Folders Before installing Obsidian, you should create a folder structure that works best for how you run games and remain organized. There are frequent updates to the imported Dungeons & Dragons 5th Edition content; it is important that some sections of this folder structure remain static and unchanged for content to be easily updated; otherwise, you will get errors when updating. As a whole, we'll name the imported section "Compendium," which contains all the official rulebooks, supplements, and adventures you own. Your house rules, maps, notes, characters, and everything else will be kept outside this Compendium folder. Feel free to improvise as needed, especially if you run multiple campaigns or across various RPG systems. Later, we discuss how to rename the Compendium folder. I have included a sample 5E folder structure you can download to get you started. Please note that almost everything in this guide refers to MacOS, though I have some Windows references, too. ==[sample folder structure zip, goes here]== ## Step 2: Install Obsidian Download [Obsidian](https://obsidian.md/download); visit [Help](https://help.obsidian.md/Getting+started/Download+and+install+Obsidian) for install information. Next, you'll need to create an Obsidian Vault. Each vault has its own self-contained hidden file structure housing each project's necessary files, preferences, and plugins; everything except the Obsidian app itself. I recommend using a single vault to run all campaigns; otherwise, you'll lose many features separating campaigns or systems and work a lot harder keeping everything in sync. Below is a screenshot showing a sample hidden vault. In MacOS, to show hidden files and folders, press `shift+command+.` - do the same again to hide them. ![[_assets/_obsidian/screenshot-vault.png]] Launch Obsidian, then follow these steps. 1. To the right of **Open folder as vault**, click **Open**. 2. In the file browser, select the root folder of your gaming folder structure. 3. Click **Open**. This will create the hidden files I mentioned above. Now you have a gaming vault. Visit [Help](https://help.obsidian.md/Home) for more information or assistance. **IMPORTANT:** It's imperative that you create, move, and rename files and folders from within Obsidian directly, as it tracks files and links through its own indexing process. If you play with files and folders outside of Obsidian, it could break your vault. You can add many files and folders at once from outside your vault, close the app, and relaunch it to re-index your vault. ### Obsidian Sync On my MacOS, I've installed my Gaming Vault in my iCloud folder to sync across all my devices; however, iCloud is not fast at syncing. If you need something speedy, you could pay for [Obsidian Sync](https://obsidian.md/sync), but I found the Obsidian mobile apps lacking, so I don't need their sync. ### Obsidian Publish The Grog Space website you're reading now is a published vault. This allows you to publish selected files and folders from your vault to the web for your players to view. You can even publish images, maps, and PDFs; everything on this site is published through this feature. Later, I'll add instructions on how to set up [Obsidian Publish](https://obsidian.md/publish). ## Step 3: Install Themes Obsidian comes with two base themes: light and dark. This option sets the default color scheme to display its light or dark mode version. However, some good RPG-related themes are available for Obsidian; the best is called [ITS Theme](https://publish.obsidian.md/slrvb-docs/ITS+Theme/ITS+Theme). ITS is highly customizable and includes some specific RPG styles. To install the ITS theme, launch Obsidian and follow these steps. 1. Go to **Settings → Appearance → Themes → Manage**. 2. Search for **ITS**, then **Install and use**. To customize the ITS Theme, install the [Style Settings](obsidian://show-plugin?id=obsidian-style-settings) community plugin, then activate it. There, you'll find many style settings and features to toggle, including many [alternate themes](https://publish.obsidian.md/slrvb-docs/ITS+Theme/Alternate+Color+Schemes) related to roleplaying games. You can take things a step further by adding [CSS snippets](https://help.obsidian.md/Extending+Obsidian/CSS+snippets). ## Install Plugins Plugins turn a plain markdown editor, like Obsidian, into a powerhouse of options and features. There are two types of plugins available in Obsidian. * [Core Plugins:](https://help.obsidian.md/Plugins/Core+plugins) Officially built and supported by the Obsidian team. * [Community Plugins:](https://help.obsidian.md/Extending+Obsidian/Community+plugins) Built by the community and 3rd-party developers. Several core plugins are automatically installed. You should browse each plugin's settings, ensuring your preferences are set where you want them for this vault. Remember, each vault has its own plugins, themes, and settings. ### Community Plugins To install community plugins, follow these steps. 1. Open **Settings**. 2. Go to **Community Plugins** and select **Restricted Mode to Off**. 3. Select **Browse** to list all available community plugins. 4. **Install** plugins as needed; later, we'll discuss several here in this guide. 5. **Enable** the plugin directly after installing it, or enable it from the list of Community plugins under **Settings → Community plugins → Installed plugins**. Use the text box to filter plugins based on their name, author, and description. You can also browse available plugins in your browser by visiting [Obsidian Plugins](https://obsidian.md/plugins). ## Step 4: Add Content Begin adding content to your vault. If you do not want or need any rulesets inside your vault, you can use Obsidian to track your campaign notes, characters, and maps. If you want to go all-in and add a compendium of books and supplements, then you'll need to convert your material to markdown; this can be done in several ways. ### Copy/Paste The idea is to copy content from a non-markdown document into Obsidian as markdown text. This is a very straightforward way to enter content, but it requires a few obsidian settings to be toggled correctly, as follows. 1. Go to **Settings → Editor → Advanced**. 2. Activate **Auto Convert HTML**. This works very well from a browser to Obsidian as it automatically converts HTML to markdown when pasting or using drag-and-drop functionality; it retains most of the formatting. You can copy/paste from other documents or a PDF, but the formatting, especially tables, does not typically come through as it does from HTML. ### Export/Import To copy/paste from other documents, the content must first be exported to HTML and then opened in a browser. The conversion should work fine if the exporting app correctly translates to HTML. Try an export to DOCX, then to HTML. I've seen that work, too; just be sure to double-check table formatting. Also, many good markdown editors have import options to translate documents to markdown directly. One of the best is [PanWriter](https://panwriter.com), a GUI for [PanDoc](https://pandoc.org), a very powerful and customizable document converter. I've used these many times in the past. ### 5eTools Extraction For 5E content, the best option is to utilize [5eTools](https://5e.tools), a suite of tools for 5th Edition Dungeons & Dragons players and Dungeon Masters that runs from a server, locally or over the internet. Much work has gone into 5eTools; it represents the best single source for your 5E-related content. The idea of installing 5eTools is to gain direct access to the 5E and homebrew content. ![[_assets/_obsidian/screenshot-5etools.png]] However, the material stored within 5eTools is in JSON format, making the raw data difficult to work with. Here, we will install a few apps allowing you to extract your 5E game content into an organized markdown format. The translation and formatting from 5eTools to Obsidian are nearly perfect, and the files are updated almost weekly. Furthermore, you can extract many books and supplements from 5eTools into Obsidian all at once plus, the material is internally linked for quick access to specific content, like spells or monsters. All the official 5E material is available, with a very active community always adding homebrew and 3rd-party content. Finding and importing content you already own to Obsidian would be easy. **So, why not use 5eTools?** Good question for which I have a good answer. You can. However, like so many other sources of RPG material, there is no way to track your notes and characters in your games. Obsidian will allow you to do this and much, much more! **IMPORTANT:** The extracted content will form the core of the Compendium we mentioned earlier in [[#Step 1 Create Folders]]. This is an important concept to remember. The one downside to 5eTools is the installation process; it requires the use of a command line interface (CLI) application. On the Mac, the app is called Terminal; on Windows, it is called the Command Prompt. ## Step 5: Install Support Understanding the workings of [Terminal](https://support.apple.com/guide/terminal/welcome/mac), a command line interface (CLI) application is imperative. However, not many command prompts are needed to complete this whole process. Here, we will install a few support apps required to set up 5eTools; here is a summary of the apps. * [Homebrew](https://brew.sh) is the easiest and most flexible way to install the various tools Apple didn’t include with macOS. It can also install software without requiring the `sudo` command. We will use this app to install other software, such as GIT. * [Git](https://git-scm.com/) is a version control system that tracks changes in computer files from the internet. We'll use it to install and update 5eTools and other files. * [TTRPG Convert CLI](https://github.com/ebullient/ttrpg-convert-cli) is a utility (hosted at GitHub) to extract D&D 5E JSON data (for content you own) from 5eTools into Obsidian. To install these apps, perform the following. 1. On a Mac, go to **Applications → Utilities → Terminal**. 2. At the command prompt, copy/paste the following BASH command: > `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`, then press `ENTER`. You may be asked to enter your computer's login password to begin. 3. Next, at the command prompt, copy/paste the following HOMEBREW command: > `brew install git`, then press `ENTER`. 4. Minimize the prompting window for now; we'll return to it again later. 5. Download [TTRPG Convert CLI](https://github.com/ebullient/ttrpg-convert-cli/releases) from Github. Be sure to select the latest release version for your operating system. For Intel-based Macs, use `osx-x86_64`; for Apple Silicon-based Macs, use `aarch_64`. Choose appropriately for other operating systems. 6. Create a new permanent folder called `5eTools2MD`. Move the newly downloaded `TTRPG-Convert-CLI` here and extract the ZIP file. This is where we'll keep 5eTools and extract the Compendium; later, we will move the Compendium folder. Once the ZIP file is extracted, this will reveal a new `bin` folder, and within is the `ttrpg-convert` file. This is the extraction app. Next, we'll download 5eTools to this `bin` folder using the command prompt. ## Step 6: Install 5eTools Do NOT manually download 5eTools; we'll use the command prompt instead; this is best for updating and avoiding errors later. 1. Within the `bin` folder, perform the following to open this folder automatically in the command prompt: >**In MacOS:** `Ctrl-Click` the Path Bar at the bottom of the Finder window and select `Open in Terminal`. If you don't see the Path Bar in Finder, go to `View → Show Path Bar`. >**In Windows:** Type `cmd` into the address bar (replacing the current address). Then press `ENTER`. 2. Once the command prompt has moved to the `bin` folder, perform the following. > At the command prompt, copy/paste the following GIT command: > `git clone https://github.com/5etools-mirror-1/5etools-mirror-1.github.io.git`, then press `ENTER`. 5eTools is well over 10 GB and growing, so the download process will take some time, depending on your internet connection. 3. Get a cup of coffee while the download finishes. 4. Once the download is complete, within the `bin` folder, you'll see a new folder named `5etools-mirror-1.github.io`; **Do not rename or move this folder or its files.** 5eTools is now installed but will not run locally in a browser yet; if needed, that comes later. ## Step 7: Extract Content With 5eTools installed, you can now extract your 5E content using the TTRPG Convert CLI app. 1. At the command prompt, copy/paste the following command: >**In MacOS:** `./ttrpg-convert --index -o Converted 5etools-mirror-1.github.io/data`, then press `ENTER`. >**In Windows:** `ttrpg-convert.exe --index -o Converted 5etools-mirror-1.github.io/data`, then press `ENTER`. 2. This will begin the extraction process, converting the 5E SRD to markdown. When complete, you'll see a new folder inside of `bin` called `Converted`, and within is a Compendium of 5E content. Move the Compendium folder to the root of your vault. You now have a basic 5E ruleset in markdown. **Do not rename or move this folder or its files.** If this is enough to get you started, then have fun gaming. If you have more content you own and need to extract more, then read on. ==BELOW IS A WORK IN PROGRESS. MORE INSTRUCTIONS COMING SOON== ## Step 8: Change the Port By default, 5eTools is hosted locally on Port 5000. Change the port to avoid conflicts and errors before you run 5eTools. 1. In Finder (or Windows Explorer), browse to the _5eTools_ root folder, and in a text or code editor, open the file named `package.json`. > Scroll down to (approx.) `line 37: "serve:dev": "http-server -c-1 --cors --port 5000"` . 2. Change the port to another number, like `5432`, then `SAVE` the file. When activating 5eTools, if you get an error claiming the port is being used by another application or device, return to the above file and change it to another port number. Be aware that after you update 5eTools, the setting may revert back to Port 5000. ==TO BE CONTINUED ...==