Note: Entries marked with "🔥" indicate crucial or breaking changes that might affect your current setup.
Note
If you generated content with an earlier verson of the CLI (1.x, 2.0.x, 2.1.x), you can use a templater script 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 to match your Vault.
To run the template: Use 'Templater: Open Insert Template Modal' with an existing note or 'Templater: Create new note from Template' to create a new note, and choose the migration template from the list.
@miscoined has made significant contributions to improve support for Pf2e creatures (the bestiary). 🙏🎉💖
In the event you have a bad image reference and the copy fails, you can set a fallback path for an image that should be used instead.
"images": {
"fallbackPaths": {
"img/bestiary/MM/Green Hag.jpg": "img/bestiary/MM/Green Hag.webp"
},
}- The key (original path) must match what is used by the JSON Source.
- The value (replacement path) should be either: a valid path to a local file or a valid URL to a remote file.
Downloading and/or copying internal or external images has been a whack-a-mole exercise with path encodings across platforms and sources. Everything should finally be fixed now.
If you use the Dice Roller plugin, useDiceRoller: true will add dice rolls to tables and in text.
If you are using the Fantasy Statblocks plugin to render your statblocks, you can now add yamlStatblocks: true to your configuration. This will strip backticks and other formatting related to dice rolls from statblock text (which will make Fantasy Statblocks happier), whether you have dice roller plugin enabled or not.
5eTools Mirror1 has been deprecated in favor of 5eTools Mirror2, which uses a separate repository for images.
When you run ttrpg-convert against mirror2 content, no images will be copied into your vault by default.
See Copying "internal" images for options on how to copy tokens and other item/spell/monster fluff images into your notes.
See Copying "external" images to copy additional images referenced in general text into your notes.
Items may have variants, which are defined as a list in the variants attribute.
- Use
resource.variantAliasesto get a list of aliases for variants - Use
resource.variantSectionLinksto get a list of links to variant sections - Iterate over the section list to generate sections (
##) for each variant
See the following examples:
- New templates:
deck2md.txt,legendaryGroup2md.txt,psionic2md.txt- Decks, when present, will be generated under
compendium/decks. Cards are part of decks. - Legendary groups, when present, will be generated under
bestiary/legendary-groups - Psionics, when present, will be generated under
compendium/psionics.
- Decks, when present, will be generated under
feat2md.txtis now also used for optional features.- The default
monster2md.txttemplate has been updated to embed the legendary group. - CSS snippets have been updated to support legendary groups embedded in statblocks.
- 🔥 Variant rules include the source in the file name: this avoids duplicates (and there were some).
- 🔥 5eTools changed the classification for some creatures, which moves them in the bestiary. Specifically: the Four-armed troll is a giant (and not an npc), a river serpent is a monstrosity rather than a beast, and ogre skeletons and red dracoliches are both undead.
- 🔥 Better support for table rendering has superceded dedicated/hand-tended random name tables. All of the tables are still present, just in different units more directly related to source material.
- 🔥 Change to monster template attributes: Legendary group attributes have been simplified to
nameanddesc, just like other traits. See the default monster template for an example.
If you use the Templater plugin, you can use a templater script 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 to match your Vault.
✨ New template documentation is available in docs. Content is generated from javadoc in the various *.qute packages (for template-accessible fields and methods). It may not be complete.. PRs to improve it are welcome.
-
🔥 A leading slash (
/) is no longer used at the beginning of compendium and root paths. This should allow you to move these two directories around more easily.- I recommend that you keep the compendium and rules sections together as big balls of mud.
- If you do want to further move files around, do so from within obsidian, so obsidian can update its links.
-
🔥 D&D 5e subclasses now use the source of the subclass in the file name.
If you use the Templater plugin, you can use a templater script 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 to match your Vault.
-
🎨 CSS styles for D&D 5e and Pathfinder are now available in
examples/css-snippets. -
📝 Admonitions are also available for import:
Note:
admonitions-5e.jsonandother-admonitions.jsonuse colors from CSS snippets to adjust for light and dark mode.
If you are using the default templates and want to render dice rolls, set
useDiceRoller to true to use dice roller strings when replacing dice {@dice }, and {@damage } strings. This can be set differently for either "5e" or
"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.
See examples/config for the general structure of config.
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.
To display all images, you can do something like this:
{#each resource.fluffImages}
{/each}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).
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:
{#if resource.fluffImages && resource.fluffImages.size > 0 }{#let first=resource.fluffImages.get(0)}
{/let}{/if}
...
{#each resource.fluffImages}{#if it_index != 0}
{/if}{/each}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).
.json5e-background div[src$="#center"],
.json5e-item div[src$="#center"],
.json5e-monster div[src$="#center"],
.json5e-race div[src$="#center"],
.json5e-spell div[src$="#center"] {
text-align: center;
}
.json5e-background div[src$="#center"] img,
.json5e-item div[src$="#center"] img,
.json5e-monster div[src$="#center"] img,
.json5e-race div[src$="#center"] img,
.json5e-spell div[src$="#center"] img {
height: 300px;
}
.json5e-background div[src$="#right"],
.json5e-item div[src$="#right"],
.json5e-monster div[src$="#right"],
.json5e-race div[src$="#right"],
.json5e-spell div[src$="#right"] {
float: right;
margin-left: 5px;
}
.json5e-background div[src$="#right"] img,
.json5e-item div[src$="#right"] img,
.json5e-monster div[src$="#right"] img,
.json5e-race div[src$="#right"] img,
.json5e-spell div[src$="#right"] img {
height: 300px;
}
.rendered-widget .admonition-statblock-parent,
.markdown-rendered .admonition-statblock-parent,
.markdown-preview-section .admonition-statblock-parent {
clear: both;
}Notes:
- I recommend constraining the image height (rather than the width) in your CSS snippet for images.
- The above snippet also adds a
clearsetting to the admonition parent. Some text descriptions are shorter than the constrained image height. Settingclear: bothonadmonition-parentensures that images floated to the right do not impact thestatblockdisplay. - This configuration is in the compendium.css snippet.
- There is an example for each type in the example templates directory directory. Relevant file names start with
images-.
Use convert to import source text for books and adventures that you own:
"convert": {
"adventure": [
"WBtW"
],
"book": [
"PHB"
]
}Specify templates in json:
"template": {
"background": "path/to/template.txt",
}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.
You can place this configuration one file or several, your choice.
Text for changes to spells at higher levels is added to spells a little differently depending on how complicated the spell is.
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.
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.
The default spell template (spell2md.txt) 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.
optfeaturetext is rendered (Tortle package)flowchartsis rendered as a series offlowchartcallouts
Use the admonition plugin to create a customflowchartcallout with an icon of your choice.- The adventuring gear tables from the PHB have been corrected
As shown in monster2md-scores.txt, you can now access ability scores directly to achieve alternate layouts in templates, for example:
- STR: {resource.scores.str} `dice: 1d20 {resource.scores.strMod}`
- DEX: {resource.scores.dex} `dice: 1d20 {resource.scores.dexMod}`
- CON: {resource.scores.con} `dice: 1d20 {resource.scores.conMod}`
- INT: {resource.scores.int} `dice: 1d20 {resource.scores.intMod}`
- WIS: {resource.scores.wis} `dice: 1d20 {resource.scores.wisMod}`
- CHA: {resource.scores.cha} `dice: 1d20 {resource.scores.chaMod}`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).
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).
If you use the Templater plugin, you can use a templater script 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.
Symbols and tokens have changed in structure. Custom templates will need a bit of adjustment.
For bestiary tokens:
{#if resource.token}
{/if}For deities:
{#if resource.image}
{/if}