> For the complete documentation index, see [llms.txt](https://salvatos.gitbook.io/kanka-cookbook/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://salvatos.gitbook.io/kanka-cookbook/power-users/using-transclusion.md).
# Using transclusion
This article describes the different ways you can leverage transclusion ([Wikipedia](https://en.wikipedia.org/wiki/Transclusion)) on Kanka, in other words how to make one piece of content (the "master copy") show up in more than one place without having to update all occurrences individually. To lead with a practical example, imagine you’re writing a Quest and want to see the stats of the villain’s weapon. You have an Object entry specifically for that information, but you’d rather see it right here in the Quest while you run the game than open it in another tab. You could copy-paste it, but then you have two places to update if you need to make changes. With transclusion, you can embed content from one source into another entry:
This is not a feature that is central to Kanka’s design, but I have been pushing to make it more accessible in the few cases where it is usable, and this guide should help you leverage its benefits as well =)
## Where is transclusion available on Kanka?
There are only a few parts of Kanka that are specifically designed with transclusion in mind:
* Dashboard widgets, which take (partial) content from multiple entries and shows it together on a common dashboard. This can include the description, image (and banner if Premium) and pinned properties or relations. Entry preview widgets can also be set to show the properties (or character sheet) of an entry rather than its description.
* Map markers and Timeline elements, which can show an entry’s description as well as their own description.
* Abilities, which can be attached to other entries and will not only show their content there, but optionally take the "host" entry’s properties into account.
* Articles can be set to display the content of their entry’s subpages, such as Properties or Relations.
* Entry mentions (e.g. `[entity:123]`) and property mentions (e.g. `{attribute:123}`). While, in their most basic form, the former simply creates a link to an entry and the latter just shows the value of a property there is a lot more there than meets the eye, and a sizeable portion of this guide will focus on those more hidden capabilities.
* Since originally writing this guide, advanced mentions now also exist that transclude articles, character sheets and maps.
The first few don’t need much additional explaining – you simply specify what entry you want to refer to in a dashboard, timeline or map marker and it shows up there. One thing to keep in mind with entry previews on dashboards is that the ability to include pinned properties opens the door to showing more content than just the description, since you will see later on that properties can store quite a bit of information. Moreover, my [Context-Aware Classes](https://marketplace.kanka.io/plugins/31910211-f33b-47b4-8db2-47dfa8dc959e) theme can help you control what parts of a description you want to actually show depending on whether someone is looking at it from the entry’s page, from a dashboard, etc., and might inspire you to centralize information while showing it differently in various contexts.
The addition in 2023 of subpages in articles and properties/character sheets in dashboard widgets also opened up a ton of possibilities to centralize content and fully make use of each module’s features while keeping everything quickly accessible from an entry’s overview. You can find a few examples of that in my other guide [Adapting layout to context](/kanka-cookbook/css/adapting-layout-to-context.md), which can also be handy for other types of transclusion.
## The unique power of abilities
Abilities deserve a bit more attention due to their ability *(I know)* to refer to their host entry’s properties by name. For instance, if your Ability says "My eyes are {eye color}", the output will differ on every entry it’s attached to based on ***that entry***’s "eye color" property. It’s the only entry category that is designed to be subordinate to other entries in this way, and none of the other forms of transclusion we will discuss here share that advantage (normally, you need the property’s unique ID to cross-reference it, e.g. `{attribute:6876453}`, which is a little tedious to set up).
By design, their purpose is to make a common piece of information available in several other places. Typically they are used on characters for things like spells, powers or feats, but they can actually be attached to other categories of entry as well. You could use them as a rules reminder on relevant Objects or Quests, as a shared notepad for a party’s players on their respective characters, as a reminder of important cultural aspects of all Locations in a certain area... And just like with Context-Aware Classes, you can use the tags on each entry and on the Abilities themselves to determine whether to show or hide certain parts of the Ability using custom CSS instead of making a different Ability for each case:
```css
body.kanka-tag-transylvania .ability[data-tags~="kanka-tag-transylvanianabilities"] {
/* Rules for Transylvanian abilities on Transylvanian entries */
}
body:not(.kanka-tag-transylvania) .ability[data-tags~="kanka-tag-transylvanianabilities"] {
/* Rules for Transylvanian abilities on non-Transylvanian entries */
}
body.entity-story .ability[data-tags~="kanka-tag-transylvanianabilities"] {
/* Rules for Transylvanian abilities in an article on the Overview page */
}
```
## The main course: transcluding with mentions
Now this is where the real fun begins for me. Let’s start simple: if you look at the [documentation for properties](https://docs.kanka.io/en/latest/features/properties.html), you’ll see that a property’s value can contain a reference to another property. For example, you could have a property called "Attack bonus" whose value is `{proficiency bonus} + {strength modifier}`, calculating from the value of two other properties. In the same entry’s description and articles, you can also have any property’s value as part of your content using a mention like `{attribute:123}`. You can get that code by typing the property’s name in the editor – for example, typing `{attac` will prompt a suggestion to insert the unique code for your "Attack bonus" property. Another way to get the mention code is to go to the Properties subpage of an entry and click a property’s name, which will copy the mention to your clipboard.
Now, the cool thing about this is that the unique mention code can also be used in *other* entries. If you want to show Bob’s current XP in Alice’s entry, you can do just that. But properties aren’t just for numbers, right? **Paragraph** attributes can have a whole bunch of HTML-formatted content in them. By extension, that means you can pin HTML content to the sidebar of the entry a property comes from, but *also* transclude that information into a bunch of other places, with a single source to keep up to date! I hope I didn’t just blow your mind, because we’re just getting started ;)
But let’s put properties aside and look at entry mentions for a bit.
You are probably familiar with the `@entry` style of mention already. You may also be using advanced mentions like `[entity:123|custom link text]`. But did you know that on top of specifying different text, you can set `page` and `field` parameters on advanced mentions? `page` simply changes the link’s URL (and is described in [the docs](https://docs.kanka.io/en/latest/features/mentions.html#advanced-mentions)), so that’s not what we’re after here. Now, `field` on the other hand can actually change the text of the link to another piece of data on the entry, dynamically keeping up to date with any changes you make to the target entry. A few examples given in the docs include `type`, `location` and `title`. That’s transclusion alright, but not terribly exciting, though it might be fun to keep track of where a character is going without updating that info manually outside of its own entry.
If you keep reading the docs, you’ll see another field is available: `entry`. ***You can actually show the entire main description of an entry somewhere else!*** It could be inside another entry’s description or article, in your dashboard header, in a… property? That’s right! Properties also parse entry mentions, not just property mentions! So you don’t even need to write HTML directly in a Paragraph property; you can just make another entry to hold that content, then mention it in a property to pin it to the sidebar:
1. Create an entry to act as the primary source for the content you want to repeat across other entries’ sidebars.
2. Copy that entry’s mention code and paste it in another entry’s property, adding the `|field:entry` parameter. For example: `Important Info`: `[entity:1337|field:entry]`.
3. Pin the property, save and repeat in other entries.
And remember when I said that pinning properties in a dashboard widget means you can show more than just the description? Turns out you can potentially show a ***lot*** more than that in one widget, from multiple sources! With judicious HTML and CSS, you could design widgets that look very different from the out-of-the-box entry preview. At one point, I even played with a layout that got rid of the description completely and kept only pinned properties in a design inspired by Wikipedia infoboxes:
Using Paragraph properties and/or transclusion, any of those fields could contain images and all sorts of formatted content beyond a few words or a number, and collect their info from several different entries.
## Comparison of transclusion methods
Now that you know the various ways content can be transcluded, you also need to be aware of the limitations of each approach.
| Feature | Descriptions (entry) | Properties |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Other mentions inside the transclusion** | Normal mentions work, but if your target entry also contains `field:entry` mentions, those will not be parsed (i.e. you can’t transclude an entry that transcludes an entry that...) and the mention code will be shown instead. | Regular mentions and transclusion both work. |
| **HTML support** | Everything allowed in entries according to [Kanka’s whitelist](https://github.com/owlchester/kanka/blob/0b0887b2c4562107b3ca33611b316229276efb58/config/purify.php). |
Tables, details/summary (spoilers), iframes and external links are stripped from properties. Everything else from the whitelist is allowed. However, if you transclude an entry’s description, that entry’s HTML is not limited, which is great for pinning spoilers or tables!
|
| **Ease of writing/updating** |
You get to use the visual editor and all provided tools and shortcuts. Since a link to the entry appears before a transcluded entry, you can easily find and edit the source of the transclusion.
|
Since property fields don’t have a visual editor, for extensive content and markup you will likely want to generate your transcluded HTML elsewhere, then paste it into the property. This also makes subsequent edits less convenient, especially since you don’t get a direct link to the source entry with property transclusions.
|
| **Ease of CSS styling** |
The transcluded content is wrapped in a span element recognizable with the mention-field-entry class, so you can style content differently when it’s transcluded. In addition, the target entry’s tags are listed on the same element under the data-entity-tags attribute and can be used to further customize its appearance.
|
The transcluded content is wrapped in a span element recognizable with the attribute-mention class, but no tags are provided. You could use the data-original-title attribute to style a specific property everywhere it’s transcluded, however. You will also likely want to remove the default background color and italics that typically appear on property values.
|
| **Ease of creating a mention** | Just type `[entryname` in the editor or in a property’s value field to get a prompt for the advanced mention, and add the `field:entry` parameter. | You need to go to the parent entity of the property, open the Properties page and copy the mention code from there by clicking on its name. (Or edit that entry’s description and start typing `{attribute-name...` to get a prompt and copy the resulting code.) |
As you can see, entry mentions are superior in most ways, but I still find that properties offer certain benefits:
* You can manage several pieces of content under a single entry, without cluttering your campaign with a series of entries that aren’t really meant to be viewed on their own. (You could make the opposite argument that it’s easier to search for master copies by looking up the entry titles, so it’s up to personal preference.) For example, I like the idea of using them to make reminders of small bits of rules like condition or status effects, weapon and armor properties, etc. like in the image below, all stored neatly in a single entry.
* You can have some HTML content directly in the property, plus one or more mentions included, and those entries can have entry and property mentions of their own, essentially giving you an additional two levels of transclusion from a more-or-less unlimited number of sources (property HTML > transcluded entries’ content > entries’ own transclusions). Likewise, you can transclude an entry that transcludes a property to get more than just that one entry’s content.
* And of course, you need properties to pin content to an entry’s sidebar, so you might as well reuse them elsewhere instead of duplicating content if that’s one of the places you want it =)
## Conclusion
I hope this gave you some ideas, and if you would like to share screenshots of cool uses you find for transclusion, I would be happy to showcase them here!
