📝 links, formatting, plugin language

ebullient · Dec 28, 2023 · 8aa301a · 8aa301a
1 parent deffdf9
commit 8aa301a
Show file tree

Hide file tree

Showing 3 changed files with 78 additions and 64 deletions.
diff --git a/README.md b/README.md
@@ -84,33 +84,6 @@ Notes:
 
 See [Other ways to run the CLI](docs/alternateRun.md) for more options to download and run the CLI.
 
-## 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.
-
-- **File names.** To avoid conflicts and issues with different operating systems, all file names are slugified (all lower case, symbols stripped, and spaces replaced by dashes). This is a familiar convention for those used to jekyll, hugo, or other blogging systems.
-
-    - File names for resources outside of the core books (PHB, MM, and DMG) have the abbreviated source name appended to the end to avoid file collisions.
-    - All files have an `aliases` attribute that contains the original name of the resource.
-
-- **Organization.** Files are generated in two roots: `compendium` and `rules`. The location of these roots is [configurable](docs/configuration.md#specify-target-paths-with-the-paths-key). These directories will be populated depending on the sources you have enabled.
-
-    - `compendium` contains files for items, spells, monsters, etc.
-    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](examples/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`.
-    - pf2e tools: `pf2e`, `pf2e-ability`, `pf2e-action`, `pf2e-affliction`, `pf2e-archetype`, `pf2e-background`, `pf2e-book`, `pf2e-delity`, `pf2e-feat`, `pf2e-hazard`, `pf2e-index`, `pf2e-item`, `pf2e-note`, `pf2e-ritual`, `pf2e-sleep`, `pf2e-trait`.
-
-- **Admonitions.**
-    - `ad-statblock`
-    - 5e tools: `ad-flowchart`, `ad-gallery`, `ad-embed-action`, `ad-embed-feat`, `ad-embed-monster`, `ad-embed-object`, `ad-embed-race`, `ad-embed-spell`, `ad-embed-table`
-    - pf2e tools: `ad-embed-ability`, `ad-embed-action`, `ad-embed-affliction`, `ad-embed-avatar`, `ad-embed-disease`, `ad-embed-feat`, `ad-embed-item`, `ad-pf2-note`, `ad-pf2-ritual`.
-
 ## Recommendations for using the CLI
 
 - 🔐 Treat generated content as a big ball of mud. Stick it in a corner of your vault *treat it as read-only*.
@@ -144,6 +117,33 @@ See [Other ways to run the CLI](docs/alternateRun.md) for more options to downlo
 
 - **Initiative Tracker** ([git](https://github.com/javalent/initiative-tracker)/[obsidian](obsidian://show-plugin?id=initiative-tracker)): Templates for rendering monsters can include information in the header to define monsters that initiative tracker can use when constructing encounters. See [Initiative Tracker plugin settings](docs/README.md#initiative-tracker) for recommendations.
 
+## 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.
+
+- **File names.** To avoid conflicts and issues with different operating systems, all file names are slugified (all lower case, symbols stripped, and spaces replaced by dashes). This is a familiar convention for those used to jekyll, hugo, or other blogging systems.
+
+    - File names for resources outside of the core books (PHB, MM, and DMG) have the abbreviated source name appended to the end to avoid file collisions.
+    - All files have an `aliases` attribute that contains the original name of the resource.
+
+- **Organization.** Files are generated in two roots: `compendium` and `rules`. The location of these roots is [configurable](docs/configuration.md#specify-target-paths-with-the-paths-key). These directories will be populated depending on the sources you have enabled.
+
+    - `compendium` contains files for items, spells, monsters, etc.
+    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](examples/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`.
+    - pf2e tools: `pf2e`, `pf2e-ability`, `pf2e-action`, `pf2e-affliction`, `pf2e-archetype`, `pf2e-background`, `pf2e-book`, `pf2e-delity`, `pf2e-feat`, `pf2e-hazard`, `pf2e-index`, `pf2e-item`, `pf2e-note`, `pf2e-ritual`, `pf2e-sleep`, `pf2e-trait`.
+
+- **Admonitions.** Generated content uses code-block-style [Admonitions](docs/README.md#admonitions) in addition to Obsidian callouts. We have [Admonition definitions](examples/admonitions/) that you can import to ensure these admonition/callout types are defined.
+    - `ad-statblock`
+    - 5e tools: `ad-flowchart`, `ad-gallery`, `ad-embed-action`, `ad-embed-feat`, `ad-embed-monster`, `ad-embed-object`, `ad-embed-race`, `ad-embed-spell`, `ad-embed-table`
+    - pf2e tools: `ad-embed-ability`, `ad-embed-action`, `ad-embed-affliction`, `ad-embed-avatar`, `ad-embed-disease`, `ad-embed-feat`, `ad-embed-item`, `ad-pf2-note`, `ad-pf2-ritual`.
+
 ## Convert 5eTools JSON data
 
 1. Create a shallow clone of the 5eTools mirror repo (which can/should be deleted afterwards):

diff --git a/docs/README.md b/docs/README.md
@@ -8,18 +8,17 @@
     - [Example templates][ex-templates]
 - [Source Map](sourceMap.md)
 
-[README.md]: https://github.com/ebullient/ttrpg-convert-cli
 [ex-ad]: ../examples/admonitions
-[ex-css]: ../examples/css-snippets
 [ex-config]: ../examples/config
-[ex-snippets]: ../examples/css-snippets
 [ex-templates]: ../examples/templates
 [def-templates]: ../src/main/resources/templates
 
 ## Recommended Obsidian plugin configuration
 
 ### Admonitions
 
+The Admonition plugin ([git](https://github.com/javalent/admonitions)/[obsidian](obsidian://show-plugin?id=obsidian-admonition)) provides additional support for codeblock-style admonitions in addition to callouts.
+
 Import one or more admonition json files in [examples/admonitions][ex-ad] to create the custom admonition types used for converted content:
 
 - [admonitions-5e.json](../examples/admonitions/admonitions-5e.json) for 5e tools
@@ -28,19 +27,17 @@ Import one or more admonition json files in [examples/admonitions][ex-ad] to cre
 
 ### Force note view mode by front matter
 
-Use this plugin to treat these generated notes as essentially read-only.  
+Use this plugin to treat these generated notes as essentially read-only.
 
-Ensure the plugin has the following options enabled (for the most consistent and least invasive experience): 
+Ensure the plugin has the following options enabled (for the most consistent and least invasive experience):
 
-- *"Ignore force view when not in front matter"*: the plugin will only change the view mode if `obsidianUIMode` is defined in the front matter.    
+- *"Ignore force view when not in front matter"*: the plugin will only change the view mode if `obsidianUIMode` is defined in the front matter.
 - *"Ignore open files"*: the plugin won't try to change the view mode if the file is already open.
 
 ## Fantasy Statblocks
 
 Fantasy Statblocks ([git](https://github.com/javalent/fantasy-statblocks)/[obsidian](obsidian://show-plugin?id=obsidian-5e-statblocks)) maintains a bestiary of monsters. It has its own (handlebars-basted) templates for monster statblocks.
 
-The CLI can generate notes that will populate the bestiary, see [5eTools example templates](../examples/templates/tools5e/README.md#5etools-alternate-monster-templates). 
-
 To populate *Fantasy Statblocks* from your notes, use the following settings:
 
 - General Settings:
@@ -49,6 +46,21 @@ To populate *Fantasy Statblocks* from your notes, use the following settings:
     - Enable Parse Frontmatter for Creatures
     - *Optional*: Add bestiary folders to constrain where the plugin looks for monsters
 
+You also need to generate content using [templates][5eTools templates] that will populate the bestiary.
+
 ## Initiative Tracker
 
-Initiative Tracker ([git](https://github.com/javalent/initiative-tracker)/[obsidian](obsidian://show-plugin?id=initiative-tracker))
+The Initiative Tracker ([git](https://github.com/javalent/initiative-tracker)/[obsidian](obsidian://show-plugin?id=initiative-tracker)) plugin for Obsidian allows you to keep track of initiative and turn order during combat encounters in tabletop role-playing games.
+
+- Basic Settings
+    - *Optional*: Embed statblock-link content in the creature view.  
+        Enable this if you use markdown statblocks and want to see the statblock content in the creature view.
+        `statblock-link` must be set in the frontmatter.
+- Plugin Integrations
+    - *Optional*: Sync monsters from TTRPG Statblocks  
+        Enable this if you use the Fantasy Statblocks plugin and want to sync monsters from your notes to the Initiative Tracker.
+
+        - See [Fantasy Statblocks](#fantasy-statblocks) section for recommended settings.
+        - Make sure you're using compatible [templates][5eTools templates] for your monsters.
+
+[5eTools templates]: ../examples/templates/tools5e/README.md#5etools-alternate-monster-templates
diff --git a/examples/templates/tools5e/README.md b/examples/templates/tools5e/README.md
@@ -37,46 +37,48 @@ Some 5eTools data types have fluff images.  These templates include those images
 
 ## 5eTools alternate monster templates
 
-- **Markdown statblock with minimal YAML frontmatter** for use with *Initiative Tracker*
+- **Markdown statblock with minimal YAML frontmatter** for use with *Fantasy Statblock* and *Initiative Tracker* plugins
+    - Monsters, objects, and vehicles that have `statblock: true` will populate the *Fantasy Statblock* bestiary.
+    - *Initiative Tracker* only needs a few elements from the statblock for encounter building. `{resource.5eInitiativeYaml}` will emit only those elements.
+    - The `statblock-link` is used by *Initiative Tracker* to embed the markdown statblock in the creature view.
     - [monster2md-yamlStatblock-header.txt](monster2md-yamlStatblock-header.txt)
     - [object2md-yamlStatblock-header.txt](object2md-yamlStatblock-header.txt)
-    - The important frontmatter elements of this example:
 
-        ```yaml
-        statblock: true
-        statblock-link: "#^statblock"
-        {resource.5eInitiativeYaml}
-        ```
+    The important frontmatter elements of this example:
 
-    - In the body of the note:
+    ```yaml
+    statblock: true
+    statblock-link: "#^statblock"
+    {resource.5eInitiativeYaml}
+    ```
 
-        ````markdown
-        ```ad-statblock
-        ...statblock content...
-        ```c
-        ^statblock
-        ````
+    In the body of the note:
 
-    - Monsters, objects, and vehicles that have `statblock: true` will populate the *Fantasy Statblock* bestiary.
-    - *Initiative Tracker* only needs a few elements from the statblock for encounter building. `{resource.5eInitiativeYaml}` will emit only those elements.
-    - The `statblock-link` is used by *Initiative Tracker* to embed the markdown statblock in the creature view.
-- **5eTools *Fantasy Statblock* `statblocks` in the body**
+    ````markdown
+    ```ad-statblock
+    ...statblock content...
+    ```c
+    ^statblock
+    ````
+
+- ***Fantasy Statblock* `statblock` in the body**
     - Monsters, objects, and vehicles that have `statblock: inline` will populate the *Fantasy Statblock* bestiary.
     - [monster2md-yamlStatblock-body.txt](monster2md-yamlStatblock-body.txt)
     - [object2md-yamlStatblock-body.txt](object2md-yamlStatblock-body.txt)
-    - The important frontmatter elements of this example:
 
-        ```yaml
-        statblock: inline
-        ```
+    The important frontmatter elements of this example:
+
+    ```yaml
+    statblock: inline
+    ```
 
-    - In the body of the note:
+    In the body of the note:
 
-        ````markdown
-        ```statblock
-        {resource.5eStatblockYaml}
-        ```
-        ````
+    ````markdown
+    ```statblock
+    {resource.5eStatblockYaml}
+    ```
+    ````
 
 - **Markdown statblock, alternate score display** - [monster2md-scores.txt](monster2md-scores.txt) (similar will work for objects)