Should caption be displayed as main title?

As a user whose native language is not English, my expectations are this:
In any case, as long as the caption exists, it is the title of the tiddler displayed to the viewer,
while title is mainly used internally as tiddler ID,
It only shows if the caption doesn’t exist.

The current situation on Tiddlywiki is that,
In some places title dominates, in others caption dominates.

This proposal, maybe more just my own needs.

In order to promote Tiddlywiki to Chinese users,
I often need to translate English tiddler into Chinese,
There is no problem with translating the content of the article,
But translating (modifying) the title of tiddler will have unexpected troubles (such as link failure, etc.).

I figured this would be less of an issue if the caption was displayed in preference to the title in any case.

Perhaps there are very few people who have such a need.
But on the other hand, what’s the harm in doing this?

You can do this easily in your tiddlywikis:

  1. clone $:/config/ViewTemplateTitleFilters/default tiddler and:
    • change title to $:/config/ViewTemplateTitleFilters/caption
    • change text to [[$:/core/ui/ViewTemplate/title/caption]]
    • add field list-before with value $:/config/ViewTemplateTitleFilters/default
  2. clone $:/core/ui/ViewTemplate/title/default tiddler and:
    • change title to $:/core/ui/ViewTemplate/title/caption
    • change text to:
\whitespace trim
<h2 class="tc-title">
<$view field="caption"><$view field="title"/></$view>

These two new tiddlers can easily be imported in any new wiki for instant result.


  • These tiddlers use the cascades mechanism to change the contents of the displayed title without overwriting any core tiddler
  • The <$view> widget displays its contents when the field parameter value doesn’t exist, providing a nice fallback to title field when caption is not defined.


Although the previous post provides a working solution, I don’t think caption should be used as a translation for the title, because its contents is often different than the tiddler title, so caption should also be translated for the case it is displayed in some tiddlers (<<list-links>> macro for example).

I think a new field should be used for title translation, named after the language it’s translated to, something like title-cn or cn.title. This method would allow more than one translation to coexist in the same wiki, although not perfectly: there would still be one single caption field…


Thanks Fred for your answer.
If I had the option, I would like to add a new field to translate.
Custom title templates only work in reading view, I expect a translated title to work outside of edit view.

For your use case, aliases might work as well:

I sometimes use the native language and add English aliases or vice versa.

You’d still want to change the view template to better highlight one or more aliases rather than the title.

I’ve designed this kind of behavior for a somewhat different reason: for bibliographic databases (for example), it’s great to be able to have italicized words within a tiddler’s reader-facing header (Plato, Crito as pseudo-title). The caption field can handle italics and other special formatting, while the title field cannot.


At the moment captions are “short titles” used in tabs and the TOC. I would suggest, that you use a “subtitle” field to replace the title field if you need to.

1 Like

In order to do this, one needs to replace the <$view> widget by a <$transclude> in the viewtemplate like this:

\whitespace trim
<h2 class="tc-title">
<$transclude field="caption"><$view field="title"/></$transclude>

The <$transclude> widget has the same behavior as the <$view> widget regarding its contents.


I think however we could perhaps use the new cascade mechanism;

  • In a solution I developed earlier you can add an empty field alt-title to any tiddler and it will use one of a few different titles or if the alt-title field has its own value.

alternate-title.json (2.2 KB)

Why isn’t this in the core? I just google across this, and I decided to make a PR, so I don’t need to do this in every plugins.

It’s much closer to being in the core than before (given the cascade affordance), but this option is probably something that new users of several solutions such as streams (as well as my biblio solution under development) would want to access easily.

In case a novice browsing this thread would like some help finding the relevant cascade mechanism, here’s a screenshot:

And then the tiddler at $:/ui/ViewTemplate/title/useCaption has contents like this:

\whitespace trim
<h2 class="tc-title">

If you create a new tiddler and the caption is set to something different, all lists now use the caption and for new users it is easy to loose the tiddler. If we did this to the tiddlers in the story this may get even more confusing. For this reason I added an indicator to titles using the caption. You can turn it off, but having it by default may be wise if added to the core.

  • we may introduce a tool tip with the real title

My use case is mostly with random generated title, like described in What’s the standard way to not writing Title.

Maybe it is better for me to include a custom cascade in those plugins that generate the tiddler with random title?

I would be more tempted to use something that generates titles from the context. For example for a projectname generate titles synch as projectname item N so you know what it relates to.

In some ways a feature of captions is in a way multiple tiddlers with what looks like they can have the same name.

I’ve been showing caption instead of title, AND :grimacing: I have some regrets…

(Granting perhaps for some projects — where public / reader and author are totally separate — one could let the cascade show ONLY a caption, because, say, “They don’t need to see what’s under the hood”… But it’s usually helpful for me, as author, to be able to distinguish title field from caption field at a glance!)

I now think the best practice, for most projects, is NOT to suppress real title entirely, but to make the caption prominent in the titlebar area (playing semantic role of “heading” for the content), while keeping the actual title visible somehow (or at the very least some clear visual indicator of the fact that one is seeing a caption there, rather than contents of the title field).

I appreciate the spirit of this comment above by @TW_Tones:

Still, I think I want something more constantly visible than a tooltip, such as faint text that darkens on hover…

OK, below is my current demo of a solution (four tiddlers under the caption-title-bundle tag), which together
(1) uses cascade to check for [has[caption]]
(2) per cascade, shows caption in place of title field in titlebar of tiddlers in story river. (Also applies a css class, caption-variant, so that when we’re looking at the caption (in titlebar), we can style it to mark the difference.
(3) bumps the real title, as a link, into beginning of subtitle area (but only if the caption exists)
(4) styles that subtitle-area real title link with <<colour muted-foreground>> — except hovering yields <<colour tiddler-link-foreground>>. Also styles the caption-variant class with a background color, so you can see immediately whether you’re looking at a caption.

This solution currently doesn’t work with uni-link plugin — which insists on replacing even the real title string in the subtitle area with the caption. If folks are interested (including @pmario) I could at some point look into the tweaks needed to protect a link from getting replaced by caption, exactly when the link is in this particular kind of location or role.

1 Like

The uni-link plugin has a global option to show the caption or subtitle field in alias links. Creating this option was a mistake, because it’s not flexible enough. It’s only there for backwards compatibility.

That’s why the “alias-link” that should be used is [[alias-link|?s]] which is a shortcut for [[alias-link|?subtitle]]. This possibility is more flexible than a global setting.

For me the “subtitle” field is more important than “caption”. That’s why it takes precedence in my plugins but uni-link does not modify the tiddler title in the ViewTemplate. uni-link only modifies [[tiddler links]]

For me the tiddler ViewTemplate looks like this:

Where I add the “real title” as an H1 into the tiddler text. This allows me to keep the tiddler title unique and just change the H1 as needed. No side effects

1 Like

I am yet to see your solution in action, but my own was a proof of concept I designed to fill a gap. It was closely related to my masquerade solution.

This was a responce to this topic alone.

  • yes


I have the same view as you that it was importiant to know when a caption, alt-title, or masquerade tiddler title was in use especialy as a designer or author. I used the unicode letters inside a circle and superscript to indicate this after the title, but have an option to toggle thier display.

Hm, it seems to me that if the setting “treat titles as links” is on, then uni-link does affect even the tiddler title as it displays in titlebar. (And I always do have that setting on, because of my heavy use of linkstyle features.) At any rate, my concern just now was not about uni-link’s effects on the titlebar, but rather its effects on trying to display the real title as a link within the subtitle.

Of course, I understand that you have solutions that work for you and have clear logic. At this point, I’m already highly invested in leveraging the caption field (on a number of projects), so I’m trying to develop a caption-as-title (in titlebar) solution that does add better visual clarity (to recognize title vs caption), and doesn’t depend on other plugins. Still, it will be ideal to avoid actually clashing with uni-link. I’ll explore some more!

Have you looked at my alt-title or masquerade solutions? they may do what you want, or give you a platform to innovate?

  • I will provide more details if asked.

I am reviewing my “alt-title and masquerade solutions” and I intentionally left caption out of it, because captions have their use as “short titles” in lists. That is why I would instead use the alt-title field. I need to add the aforementioned indicator use to show an alt-title is in use.

eg my Masquerading tiddlers optionally look like this;

  • The icon indicates it has an [object-type[page]]
  • The real title is $:/TagManager, but this tiddler means it can be found with a standard search because it is not a system tiddler.
  • Tiddlers that are masqueraded can have their own fields and tags etc… but the text appears like the tiddler they copy.


caption: only for tabs, shame but the semantics of a caption have been lost as a result
subtitle: my preferred titling method
title: TW’s unique “id”
uuid: my unique id used for most linking I need