|
| 1 | +# Additional CLI Options and Help |
| 2 | + |
| 3 | +- [Alternate Ways to Run the CLI](alternateRun.md) |
| 4 | +- [Configuring the CLI](configuration.md) |
| 5 | +- [Configuration Examples][examples/config] |
| 6 | +- [Changelog Archive](#changelog-archive) |
| 7 | + |
| 8 | +[README.md]: https://github.com/ebullient/ttrpg-convert-cli |
| 9 | +[examples/config]: https://github.com/ebullient/ttrpg-convert-cli/tree/main/examples/config |
| 10 | +[ex-snippets]: https://github.com/ebullient/ttrpg-convert-cli/tree/main/examples/css-snippets |
| 11 | +[ex-templates]: https://github.com/ebullient/ttrpg-convert-cli/tree/main/examples/templates |
| 12 | +[def-templates]: https://github.com/ebullient/ttrpg-convert-cli/tree/main/src/main/resources/templates |
| 13 | + |
| 14 | +## Alternate Ways to Run the CLI |
| 15 | + |
| 16 | +For details, see [Alternate Ways to Run the CLI](alternateRun.md). |
| 17 | + |
| 18 | +## Configuring the CLI |
| 19 | + |
| 20 | +Detailed instructions for configuring the CLI are available in [Configuring the CLI](configuration.md). |
| 21 | +Configuration file examples are also available in the [Examples][examples/config] directory. |
| 22 | + |
| 23 | +## Changelog Archive |
| 24 | + |
| 25 | +**For the latest changes, see the project [README.md][].** |
| 26 | + |
| 27 | +--- |
| 28 | + |
| 29 | +**Note:** Entries marked with "🔥" indicate crucial or breaking changes that might affect your current setup. |
| 30 | + |
| 31 | +### 🔖 1.1.1: Dice roller in statblocks and text |
| 32 | + |
| 33 | +If you are using the default templates and want to render dice rolls, set |
| 34 | +`useDiceRoller` to true to use dice roller strings when replacing dice `{@dice |
| 35 | +}`, and `{@damage }` strings. This can be set differently for either "5e" or |
| 36 | +"pf2e" configurations. Please note that if you are using a custom template and fantasy statblocks, you do **not** need to set the dice roller in your config. Fantasy statblocks will take care of the rendering itself. |
| 37 | + |
| 38 | +See [examples/config][] for the general structure of config. |
| 39 | + |
| 40 | +### 🔖 1.1.0: Images for backgrounds, items, monsters, races, and spells |
| 41 | + |
| 42 | +The conversion tool downloads fluff images into `img` directories within each type, e.g. `backgrounds/img` or `bestiary/aberration/img`. These images are unordered, and are not referenced in entry text. Templates must be modified to include them. |
| 43 | + |
| 44 | +To display all images, you can do something like this: |
| 45 | + |
| 46 | +``` |
| 47 | +{#each resource.fluffImages} |
| 48 | +{/each} |
| 49 | +``` |
| 50 | + |
| 51 | +Note that the line above ends with two spaces, which serves as a line break when you have strict line endings enabled. You may need something a little different to get things to wrap the way you want in the case that there are multiple images (which is infrequent for these types). |
| 52 | + |
| 53 | +You can also use two separate blocks, such that the first image is used at the top of the document, and any others are included later: |
| 54 | + |
| 55 | +``` |
| 56 | +{#if resource.fluffImages && resource.fluffImages.size > 0 }{#let first=resource.fluffImages.get(0)} |
| 57 | + |
| 58 | +{/let}{/if} |
| 59 | +... |
| 60 | +
|
| 61 | +{#each resource.fluffImages}{#if it_index != 0} |
| 62 | +{/if}{/each} |
| 63 | +``` |
| 64 | + |
| 65 | +Notice the `#right` and `#center` anchor tags in the example above. The following CSS snippet defines formatting for two anchor tags: `#right` (which will float the image to the right) and `#center` (which will display the image as a centered block). |
| 66 | + |
| 67 | +```css |
| 68 | +.json5e-background div[src$="#center"], |
| 69 | +.json5e-item div[src$="#center"], |
| 70 | +.json5e-monster div[src$="#center"], |
| 71 | +.json5e-race div[src$="#center"], |
| 72 | +.json5e-spell div[src$="#center"] { |
| 73 | + text-align: center; |
| 74 | +} |
| 75 | +.json5e-background div[src$="#center"] img, |
| 76 | +.json5e-item div[src$="#center"] img, |
| 77 | +.json5e-monster div[src$="#center"] img, |
| 78 | +.json5e-race div[src$="#center"] img, |
| 79 | +.json5e-spell div[src$="#center"] img { |
| 80 | + height: 300px; |
| 81 | +} |
| 82 | +.json5e-background div[src$="#right"], |
| 83 | +.json5e-item div[src$="#right"], |
| 84 | +.json5e-monster div[src$="#right"], |
| 85 | +.json5e-race div[src$="#right"], |
| 86 | +.json5e-spell div[src$="#right"] { |
| 87 | + float: right; |
| 88 | + margin-left: 5px; |
| 89 | +} |
| 90 | +.json5e-background div[src$="#right"] img, |
| 91 | +.json5e-item div[src$="#right"] img, |
| 92 | +.json5e-monster div[src$="#right"] img, |
| 93 | +.json5e-race div[src$="#right"] img, |
| 94 | +.json5e-spell div[src$="#right"] img { |
| 95 | + height: 300px; |
| 96 | +} |
| 97 | + |
| 98 | +.rendered-widget .admonition-statblock-parent, |
| 99 | +.markdown-rendered .admonition-statblock-parent, |
| 100 | +.markdown-preview-section .admonition-statblock-parent { |
| 101 | + clear: both; |
| 102 | +} |
| 103 | +``` |
| 104 | + |
| 105 | +Notes: |
| 106 | + |
| 107 | +- I recommend constraining the image height (rather than the width) in your CSS snippet for images. |
| 108 | +- The above snippet also adds a `clear` setting to the admonition parent. Some text descriptions are shorter than the constrained image height. Setting `clear: both` on `admonition-parent` ensures that images floated to the right do not impact the `statblock` display. |
| 109 | +- This configuration is in the [compendium.css snippet][ex-snippets]. |
| 110 | +- There is an example for each type in the [example templates directory][ex-templates] directory. Relevant file names start with `images-`. |
| 111 | + |
| 112 | + |
| 113 | +### 🔖 1.0.18: You can put more things in json input now! |
| 114 | + |
| 115 | +Use `convert` to import source text for books and adventures that you own: |
| 116 | + |
| 117 | +```json |
| 118 | + "convert": { |
| 119 | + "adventure": [ |
| 120 | + "WBtW" |
| 121 | + ], |
| 122 | + "book": [ |
| 123 | + "PHB" |
| 124 | + ] |
| 125 | + } |
| 126 | +``` |
| 127 | + |
| 128 | +Specify templates in json: |
| 129 | + |
| 130 | +```json |
| 131 | + "template": { |
| 132 | + "background": "path/to/template.txt", |
| 133 | + } |
| 134 | +``` |
| 135 | + |
| 136 | +Be careful of paths here. Relative paths will be resolved depending on where the command is run from. Absolute paths will be machine specific (most likely). Use forward slashes for path segments, even if you're working on windows. |
| 137 | + |
| 138 | +You can place this configuration one file or several, your choice. |
| 139 | + |
| 140 | +### 🔖 1.0.16: Sections in Spell text |
| 141 | + |
| 142 | +Text for changes to spells at higher levels is added to spells a little differently depending on how complicated the spell is. |
| 143 | + |
| 144 | +Some spells effectively have subsections. Create or Destroy Water, from the PHB, has one subsection describing how water is created, and another describing how it is destroyed. In many layouts, there is just a bit of bold text to visually highlight this information. I've opted to make these proper sections (with a heading) instead, because you can then embed/transclude just the variant you want into your notes where that is relevant. |
| 145 | + |
| 146 | +If a spell has sections, then "At Higher Levels" will be added as an additional section. Otherwise, it will be appended with `**At Higher Levels.**` as leading eyecatcher text. |
| 147 | + |
| 148 | +The [default spell template (spell2md.txt)][def-templates] will test for sections in the spell text, and if so, now inserts a `## Summary` header above the Classes/Sources information, to ensure that the penultimate section can be embedded cleanly. |
| 149 | + |
| 150 | +### 🔖 1.0.15: Flowcharts, optfeature in text, styled rows |
| 151 | + |
| 152 | +- `optfeature` text is rendered (Tortle package) |
| 153 | +- `flowcharts` is rendered as a series of `flowchart` callouts |
| 154 | + Use the admonition plugin to create a custom `flowchart` callout with an icon of your choice. |
| 155 | +- The adventuring gear tables from the PHB have been corrected |
| 156 | + |
| 157 | +### 🔖 1.0.14: Ability Scores |
| 158 | + |
| 159 | +As shown in [monster2md-scores.txt][ex-templates], you can now access ability scores directly to achieve alternate layouts in templates, for example: |
| 160 | + |
| 161 | +``` |
| 162 | +- STR: {resource.scores.str} `dice: 1d20 {resource.scores.strMod}` |
| 163 | +- DEX: {resource.scores.dex} `dice: 1d20 {resource.scores.dexMod}` |
| 164 | +- CON: {resource.scores.con} `dice: 1d20 {resource.scores.conMod}` |
| 165 | +- INT: {resource.scores.int} `dice: 1d20 {resource.scores.intMod}` |
| 166 | +- WIS: {resource.scores.wis} `dice: 1d20 {resource.scores.wisMod}` |
| 167 | +- CHA: {resource.scores.cha} `dice: 1d20 {resource.scores.chaMod}` |
| 168 | +``` |
| 169 | + |
| 170 | +### 🔖 1.0.13: Item property tags are now sorted |
| 171 | + |
| 172 | +Property tags on items are now sorted (not alphabetically) to stabilize their order in generated files. This should be a one-time bit of noise as you cross this release (using a version before to using some version after). |
| 173 | + |
| 174 | +### 🔖 🔥 1.0.12: File name and image reference changes |
| 175 | + |
| 176 | +#### 🔥 File name changes |
| 177 | + |
| 178 | +Each file name will now contain an abbreviation of the primary source to avoid conflicts (for anything that does not come from phb, mm, dmg). |
| 179 | + |
| 180 | +***If you use the Templater plugin***, you can use [a templater script](https://github.com/ebullient/ttrpg-convert-cli/blob/main/migration/json5e-cli-renameFiles-1.0.12.md) to rename files in your vault before merging with freshly generated content. View the contents of the template before running it, and adjust parameters at the top as necessary. |
| 181 | + |
| 182 | +#### 🔥 1.0.12: Deity symbols and Bestiary tokens |
| 183 | + |
| 184 | +Symbols and tokens have changed in structure. Custom templates will need a bit of adjustment. |
| 185 | + |
| 186 | +For bestiary tokens: |
| 187 | + |
| 188 | +``` |
| 189 | +{#if resource.token} |
| 190 | +{/if} |
| 191 | +``` |
| 192 | + |
| 193 | +For deities: |
| 194 | + |
| 195 | +``` |
| 196 | +{#if resource.image} |
| 197 | +{/if} |
| 198 | +``` |
0 commit comments