From 8ceb0b75f19bf12da293cc5566870de2f916c879 Mon Sep 17 00:00:00 2001 From: Erin Schnabel Date: Mon, 16 Oct 2023 23:35:10 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Clean=20up=20recommendations;=20?= =?UTF-8?q?css=20snippets?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 72 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 50 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 8df6118fe..3c8626492 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # TTRPG convert CLI ![GitHub all releases](https://img.shields.io/github/downloads/ebullient/ttrpg-convert-cli/total?color=success) -A Command-Line Interface designed to convert TTRPG data from 5eTools (and upcoming support for Pf2eTools) into crosslinked, tagged, and formatted markdown optimized for [Obsidian.md](https://obsidian.md). +A Command-Line Interface designed to convert TTRPG data from 5eTools and Pf2eTools into crosslinked, tagged, and formatted markdown optimized for [Obsidian.md](https://obsidian.md). @@ -19,15 +19,41 @@ I use [Obsidian](https://obsidian.md) to keep track of my campaign notes. This p > 🚜 Check out [Changes that impact generated templates and files](#changes-that-impact-generated-templates-and-files) and/or release notes for breaking changes and new capabilities. -## Install the command line utility +## 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: + +- For MacOS / OSX Users: + - Start with the built-in `Terminal` application. + - [Learn the Mac OS X Command Line][] +- For Windows Users: + - Use the native [Command Prompt][] + - [Open a command prompt in a folder (Windows)][] + - [Running executables from the command line (Windows)][] + - To show emoji in Windows Commmand Prompt: `chcp 65001` and choose a font with emoji support (Consolas is one). + +[Learn the Mac OS X Command Line]: https://blog.teamtreehouse.com/introduction-to-the-mac-os-x-command-line +[Command Prompt]: https://www.digitaltrends.com/computing/how-to-use-command-prompt/ +[Open a command prompt in a folder (Windows)]: https://www.lifewire.com/open-command-prompt-in-a-folder-5185505 +[Running executables from the command line (Windows)]: https://www.techwalla.com/articles/how-to-use-quotcdquot-command-in-command-prompt-window + +## Install the TTRPG Convert CLI There are several options for running `ttrpg-convert`. Choose whichever you are the most comfortable with: -- [Use pre-built platform binary](#use-pre-built-platform-binary) (no Java required) -- [Use JBang](docs/usage/alternateRun.md#use-jbang) +- [Use a pre-built platform binary](#use-pre-built-platform-binary) (no Java required) +- [Use JBang](docs/usage/alternateRun.md#use-jbang) (hides Java invocation; sets up command aliases) - [Use Java to run the jar](docs/usage/alternateRun.md#use-java-to-run-the-jar) - [Build from source](docs/usage/alternateRun.md#build-and-run-from-source) -- **Using Windows?** See the [Windows README](README-WINDOWS.md) +- **Using Windows?** + - See the [Windows README](README-WINDOWS.md) + - Obsidian TTRPG Tutorials: [TTRPG-Convert-CLI 5e][] or [TTRPG-Convert-CLI PF2e][] + +[TTRPG-Convert-CLI 5e]: https://obsidianttrpgtutorials.com/Obsidian+TTRPG+Tutorials/Plugin+Tutorials/TTRPG-Convert-CLI/TTRPG-Convert-CLI+5e +[TTRPG-Convert-CLI PF2e]: https://obsidianttrpgtutorials.com/Obsidian+TTRPG+Tutorials/Plugin+Tutorials/TTRPG-Convert-CLI/TTRPG-Convert-CLI+PF2e ### Use pre-built platform binary @@ -46,29 +72,29 @@ We'll use this command in the instructions below. Notes: - Folks familar with command line tools can add the `bin` directory to their path to make the command available from anywhere. +- _MacOS permission checking_ (unverified executable): `xattr -r -d com.apple.quarantine /ttrpg-convert` + +**Looking for a different method?** See [Alternate ways to run the CLI](docs/usage/alternateRun.md) for more options to download and run the CLI. -Notes for Windows: -- [Open a command prompt in a folder (Windows) ](https://www.lifewire.com/open-command-prompt-in-a-folder-5185505) -- [Running executables from the command line (Windows)](https://www.techwalla.com/articles/how-to-use-quotcdquot-command-in-command-prompt-window) -- To show emoji in Windows Commmand Prompt: `chcp 65001` and choose a font with emoji support (Consolas is one). You can also try the new Windows Terminal (`wt.exe`). -- See the [Windows README](README-WINDOWS.md) +## 🔮 Recommendations for using the CLI -Notes for MacOS: +- 🔐 Keep generated content isolated in your vault and *treat it as read-only*. + Content is updated, or you bought another adventure... + + Trust me, you will want to regenerate content from time to time. It's easier to do that if you don't have to worry about your own edits. -- MacOS permission checking (unverified executable): `xattr -r -d com.apple.quarantine /ttrpg-convert` +- 🔎 Have the CLI generate output into a separate directory and use a comparison tool to preview changes. -**Looking for a different method?** See [Alternate ways to run the CLI](docs/usage/alternateRun.md) for more options to download and run the CLI. + You can use `git diff` to compare arbitrary directories, for example: + ``` + git diff --no-index vault/compendium/bestiary generated/compendium/bestiary + ``` -## Conventions +- 📑 Use a copy tool that only updates modified files, like [rsync][], to avoid unnecessary file copying when updating your vault. Use the checksum option (`-c`) to compare file contents; the file modification date is meaningless given generated files are recreated when the tool is run. + +[rsync]: https://stackoverflow.com/a/19540611 -> 💭 **Recommendations** -> - Keep generated content isolated in your vault and treat it as read-only. -> - Run the CLI against a separate directory. Use a comparison tool to preview changes. -> You can use `git diff` to compare arbitrary directories, for example: -> ``` -> git diff --no-index vault/compendium/bestiary generated/compendium/bestiary -> ``` -> - Use a copy tool that only updates modified files, like rsync or robocopy, to avoid unnecessary file copying when updating your vault. +## Conventions - **Links.** Documents generated by this plugin will use markdown links rather than wiki links. A [css snippet](examples/css-snippets/hide-markdown-link-url.css) can make these links less invasive in edit mode by hiding the URL portion of the string. @@ -82,6 +108,8 @@ Notes for MacOS: The `compendium` directory is further organized into subdirectories for each type of content. For example, all items are in the `compendium/items` directory. - `rules` contains files for conditions, weapon properties, variant rules, etc. + + - `css-snippets` will contain **CSS files for special fonts** used by some content. You will need to copy these snippets into your vault (`.obsidian/snippets`) and enable them (`Appearance -> Snippets`) to ensure all content in your vault is styled correctly. - **Styles.** Every document has a `cssclasses` attribute that assigns a CSS class. We have some [CSS snippets](#optional-css-snippets) that you can use to customize elements of the compendium. - 5e tools: `json5e-background`, `json5e-class`, `json5e-deck`, `json5e-deity`, `json5e-feat`, `json5e-hazard`, `json5e-item`, `json5e-monster`, `json5e-note`, `json5e-object`, `json5e-psionic`, `json5e-race`, `json5e-reward`, `json5e-spell`, and `json5e-vehicle`.
Jump