We need a core macro similar to the toc macro to transclude all hierarchical content

Developers
#1

we need a core macro similar to the toc macro to transclude all hierarchical content, generating a linear document. This can then be used for printing or generating PDF documents.

PDF documents are a more widely accepted format than HTML. Compared to clicking through content, most people are more accustomed to flipping pages or scrolling through linear documents. People primarily need linear documents, and only secondarily need linear documents with clickable tables of contents. When sharing documents with others, I often worry that the recipient won’t know how to read this document.

Some advantages of PDF over wiki documents:

  1. PDFs are acceptable in instant messaging, whereas HTML poses barriers.

  2. AI systems accept PDF documents but reject HTML and wiki documents.

  3. From a publishing perspective, PDF is more universally compatible than HTML.

  4. HTML involves various interactive interfaces, while PDF is simple enough for everyone to read without barriers.

#2

The problem with pdf documents is they have pages. this demands design input to every page break and is not so easy to automate as PDFs page can be influenced by page and printer settings as people like to see WYSIWYG.

As a result I have come to believe an infinitely scrollable single page is better.

#3

Give this a try…

Create a tiddler (e.g., “PrintAll”) containing:

\procedure out(here)
<$list filter="[tag<here>] -[enlist<excluded>]">
   <div style="page-break-before:always;">
   <h2>{{!!title}}<hr></h2>
   <$transclude mode=block/>
   </div>
   <$set name=excluded filter="[enlist<excluded>] [<here>]">
   <$macrocall $name="out" here={{!!title}}/>
   </$set>
</$list>
\end

<$let here="HelloThere">
<$list filter="[<preview>!match[yes]]" emptyMessage=<<out>>>
   <$button>{{$:/core/images/print-button}}
      <$action-sendmessage $message="tm-open-window" $param="PrintAll" preview="yes"/>
   </$button>
</$list>

Notes:

  • The out() procedure does a “depth-first” recursion of a tag hierarchy, starting with a tiddler title stored in the <here> variable. For this example, I have hard-coded “HelloThere” as the starting tiddler. You can, of course, set this to whatever title is suitable for your purposes.
    • For each tiddler it finds, the out() procedure displays the tiddler’s title as a heading and then renders the tiddler’s text content. Note that the output is enclosed within a div that has style="page-break-before:always;". This forces a page break to occur so that each tiddler will always start on a new page. If a tiddler’s rendered content is longer than a single page, it will automatically “overflow” onto subsequent pages.
    • Also note the use of the excluded variable. This is used to prevent infinite recursion that can occur if tiddlers are tagged in a “loop” (e.g., TiddlerA tags TiddlerB, and TiddlerB tags TiddlerC, and TiddlerC tags TiddlerA). As each tiddler is “visited” in the recursion, it is added to the exclude list so it won’t be visited again.
  • Following the out() procedure definition, the main tiddler content renders a $button that opens a separate window to render the output. This is useful as a “print preview” and also isolates the content to be printed from the rest of the TiddlyWiki page. This is needed because the TWCore does not currently provide a “print this tiddler” toolbar button.
  • Note that the tm-open-window sets a variable, preview="yes", and the $button is wrapped inside a $list widget so that when viewed in the main TiddlyWiki, the button is shown, but when viewed in the separate “preview” window, the recursive output is shown.
  • To actually print the output from the preview window, use your browser’s right-click popup menu to select the native “print…” function. From there, you can usually select a “print to PDF” option to generate a PDF file.

enjoy,
-e

3 Likes
Announcing new TiddlyTools add-on: TiddlyTools/PrintTiddler
#4

Applause

The procedure is fine and can be recursively called. However, PrintAll is empty.

First, is there a widespread need for this core macro? If it’s genuinely a common requirement for many users, then as a mature core macro, It needs to have several functions. For example:

  1. Customize title styles.

  2. Set title numbering.

  3. Customize numbering formats. For example:

hh2::before {
<BR />counter-increment: section;
<BR />content: counter(chapter) "." counter(section) " ";
<BR />}

  1. Add clickable table of contents.

  2. Allow adding clickable links to jump to titles.

#5

Clever and small solution.

Is it possible to have such a button? Does it require hiding all other content in the storyriver except the current Tiddler? I was thinking that on click, a variable could be set, and through dynamic CSS, everything except that Tiddler could be excluded from printing (e.g. using @media print{…} .

title: print-thisTiddler.css
tags: $:/tags/Stylesheet
type: text/vnd.tiddlywiki

/* Dynamic stylesheet for print this tiddler */
@media print {

<$list filter="[list[$:/StoryList]] -[{excludeThisTiddler}]">
div[data-tiddler-title="<<currentTiddler>>"] {display: none}
</$list>
}

Note: data-tiddler-title="<<currentTiddler>>" is correct and "..." is needed here.
Note ii: The content of excludeThisTiddler will be set by the printThisTiddler button

1 Like
#6

The name of the tiddler containing the code should be “PrintAll” so that its content will be shown when tm-open-window is triggered to open the “preview” window.

-e

#7

It’s actually very easy to add this, and it does NOT require hiding all other content!

Instead, we use the same tm-open-tiddler method I previously demonstrated to open a “preview” window that renders only the current tiddler. Then use your browser’s right-click popup menu to choose “print…”

Put the following content in a tiddler tagged with $:/tags/ViewToolbar:

<$button class=<<tv-config-toolbar-class>> selectedClass=tc-selected tooltip="print this tiddler">
	<%if [<tv-config-toolbar-icons>match[yes]] %>{{$:/core/images/print-button}}<%endif%>
	<%if [<tv-config-toolbar-text>match[yes]]  %>@@.tc-btn-text print@@<%endif%>
	<$action-sendmessage $message="tm-open-window"/>
</$button>

Also, add a caption field containing

{{$:/core/images/print-button}} print this tiddler

so it will appear properly listed in $:/ControlPanel > Appearance > Toolbars > View Toolbar

enjoy,
-e

1 Like
#8

It worked. Thanks. Place the code in the tiddler named “PrintAll” and it will work fine.

#9

A post was split to a new topic: Announcing new TiddlyTools add-on: TiddlyTools/PrintTiddler

#10

I had AI rewrite this post.

You might not believe this, but I recently stumbled upon a real pain point: our team’s wiki system is beautifully structured — hierarchical, organized, logical. But the moment you try to print it, share it, or feed it to an AI? It’s like handing someone a puzzle instead of a document.

Think about it — who actually wants to click through five layers just to read something? Most people still crave that simple, linear experience: open, scroll, done. Or better yet — print it out, grab a coffee, and flip through pages like a real book. That’s what a “human-friendly document” looks like.

So I started wondering: what if we had a “core macro” — something like the TOC macro — that could automatically flatten all hierarchical content into a single, linear document? Like pressing a 3D pop-up book flat into a clean, scrollable PDF.

Why PDF? Because reality doesn’t care about fancy tech — it cares about what works:

  • Send a PDF over WeChat, Slack, or Teams? Everyone opens it instantly. Send HTML? People stare at it like, “Uh… how do I even read this?”
  • AI systems? They devour PDFs. Feed them HTML or wiki pages? They’ll politely (or not so politely) reject your submission.
  • From a publishing standpoint, PDF is the true universal format. HTML may be powerful, but with its buttons, menus, and collapsible sections? It’s overwhelming for ordinary users. PDF? Open and read. Zero learning curve.

Let’s be honest — what people need first is a document they can just read, smoothly, from start to finish. Clickable tables of contents? That’s a luxury feature. We often assume interactivity equals progress — but sometimes, simplicity is the real kindness.

Every time I send someone a wiki link, I hold my breath: “Will they find the right section? Will they miss a nested page? Do they even know how to navigate this?” That anxiety? Gone. The moment you send a PDF.

So let’s stop hiding knowledge behind clicks. What we need is a “Flatten Everything” button — to turn structured, branching content into a linear, universally readable, AI-friendly, printer-ready PDF. That’s what knowledge deserves: no barriers, no detours, open and accessible from the first second.

After all — no matter how brilliant your content is… if people can’t open it, can’t read it, can’t share it… it might as well not exist.

1 Like
#11

I have a feeling that this goal is useful for only a quite small minority of TiddlyWikis. There are some that are definitely hierarchical. I created one along these lines (https://charter2024.andoverct.info/), and am working on another (https://crosseye.github.io/rham-policy/). But I think such wikis are rare.

On the first tiddler of the first TW most users see, TiddlyWiki is described specifically as “non-linear”. And I think that covers most usage of it. While they might have some hierarchical, linear sections, wikis tend toward random access and surfing.

Think about tiddlywiki.com. How would you arrange a linear overview? The TOC is arranged for skimming and searching, and it’s definitely not hierarchical. And if you did still decide to print it in a hierarchical manner, would you print three copies of Filter Operators because it appears under Filters, under Reference > Filters, and under Reference > Concepts > Filter? If not, how do you decide where it goes? And of course with transcluded content, would you expect to repeat it everywhere its used or somehow change it to a reference?

It’s not that I think this is a bad idea to have, but I think its scope is fairly limited. And I’m not sure how to make it generic. My two wikis that are so hierarchical are still fairly different. The charter has a fixed hierarchy. Chapters consist of sections; sections may have subsections, and subsections may have sub-subsections. Each level has a consistent numbering scheme. The policy manual has sections, which contain numbered policies. Policies are usually broken into sections, some numbered, some not. Those sections may be subdivided, and those subdivisions themselves may be, and so on, without a fixed hierarchy. Their numbering is inconsistent. Some use roman numerals, some use arabic numbers, others use letters.

I have a difficult time imagining one macro/procedure that would easily handle both of these, never mind all the other possibilities users might have for hierarchies. But I do have a print stylesheet in place for the charter, and at least the start of one for the policy manual. Because these are linear, hierarchical documents, and can be displayed that way, this is important.

I just feel that it would be hard to capture a general mechanism that wouldn’t be to constricting. But the TW community continually surprises me, so perhaps you’ll be able to come up with something.

#12

5 posts were split to a new topic: Page breaks for printing/PDF Generation

#13

I respect that there are situations where such a document is needed. But there are public-facing wikis where this is not at all what anyone needs! (I give my students a link to my course’s learning resources page, so they can find what they need. A printed PDF of all the tiddlers would run into hundreds of pages. And it would have to strip away all the interactive elements that make it a good learning tool!)

Then again, if an LLM suggested those phrases for you (“Let’s be honest — what people need is … So let’s stop…”), that only shows us that these mediocre prose engines tend toward a breezy “everybody-think-the-same” style.

At any rate, you don’t need to convince us that PDF is always best, or is the “true universal” — you only need to find out whether there is community interest in a PDF export tool.

Even though I would never convert-to-PDF for an entire real wiki, even I experience situations where I’d like to export a set of tiddlers in PDF form.

For now, when that happens, I choose to make one container tiddler, and in that container I set up a list filter to make sure all the needed tiddlers are transcluded. (I call this the “compilation” tiddler, because it compiles all the tiddlers I wish to display.)

Two benefits of this approach:

  • It’s very easy to order the tiddlers according to a list field (which is more flexible than a simple sort, especially if you use list-before and list-after fields wisely).
  • You can decide which tiddler elements (view-templates, tags, subtitles, etc.) are displayed or hidden in the “compilation” tiddler. Perhaps they should not display the same as they do on screen! (Then again, if you do print the story river full of tiddlers, it’s also possible to have css that selectively hides or modifies elements during a print job.)
2 Likes
#14

@Springer – A little warning

If you drag & drop sort a list. All the list-before and list-after fields are deleted in the tiddlers that contain them.

Usually that’s not a problem, but in your usecase it most likely is one.

The “solution” is to use drag & drop sort only except you work with a read only wiki, where the next reload fixes the changes.

#15

In my use-case, I’ve mostly disciplined myself not to drag and drop. There’s always a reason for the order, and I prefer to encode those reasons in my use of list-before and list-after. But yes, this is a good reminder to anyone about the pitfalls of trying both ways of “fixing” a list.

#16

hihi, Yea, that’s the second option :wink:

#17

I did experiment with custom templates for my tocP - plugin. – It works, but the templates are very usecase specific. I did test it with a “streams” outline and there where some interesting results. All of it was highly experimental and not really production ready.

My toc-rewrite should be able to handle that, but I did never test it, in the way you describe it.

As I wrote it is very use-case specific. So it highly depends on the structure of your TOC and if that toc structure is already in the right order for printing. Otherwise it would need a different “print-structure” to be able to create a linear flow that is needed for printing.

#18

I have long held the view that there are content tiddlers and report, list or view tiddlers (in addition to code and others). As a result I would always create an additional tiddler to consolodate a view or multiple tiddlers and this stands for printing as well.

  • I also dislike PDF’s with bad page breaks and think we are all looking for good sharable, view not print, infinite scroll documents (with an index, contents and search)
#19

The single-page content you generated looks great. I hope that if a flatten core macro becomes available in the future, it can produce such beautiful single pages.

Here’s a thought: The knowledge structure in the human brain is non-linear, but when we need to express it, we must convert it into a linear structure.

Personal notes are non-linear, aligning with the brain’s knowledge structure. Wikis are also non-linear, well-suited for expressing complex interconnections between knowledge.

However, when the goal is information transmission, a conversion process from non-linear to linear structure is necessary to enable effective communication with others and AI. This conversion isn’t automated; it requires the author to invest significant effort and time to arrange the sequence.

Tutorials and manuals are typically linear. Currently, the content on the official TiddlyWiki website is linear. Documentation for numerous TiddlyWiki plugins uses the toc macro, which is also linear.

After reading your post, I realized that while having multiple tags for a single tiddler isn’t an issue for the toc macro, it becomes a problem when printing.

As seen in the macro from @EricShulman 's earlier post, maintaining a list of previously printed content resolves this issue. It would be even better if repeated print locations included a prompt like “This content can be found ahead at a certain point.”

Earlier I mentioned the need for a feature to customize numbering and title styles. If customization is to be avoided, then at the very least, the titles should be preceded by a numbering system like 1.1.1.7.

#20

The AI’s statement is somewhat imprecise. Not everyone requires PDFs. However, based on the information I’ve reviewed, the number of documents I’ve read far exceeds those on wiki sites.

Exporting a specific set of tiddlers to generate documentation is indeed an excellent approach. Alternatively, this functionality could be incorporated into the flatten macro to filter out a group of tiddlers possessing a particular field value.

1 Like