What is this?

Streams-fusion is an addon to the Streams plugin that lets the user fuse (merge) and export a hierarchy of nodes from a stream, into a single tiddler's wikitext or raw html.

Why would I want to do this?

Great question! You probably will not. Streams users like to edit their thoughts rapidly, jolt down ideas, leverage keyboard shortcuts extensively, and re-organize them using drag and drop features.

Once that process has taken place however, some users may wish to collapse the streams tiddlers down to a single "regular" tiddler, which may be easier to export, share with non-stream users, convert to another format, etc... It is worth pointing out the similarities with the experimental Streams-based list editor by Saq Imtiaz.

Features

• preserve the streams node hierarchy (maintains the tree structure)
• supports the following list formats:
  • unordered lists (bullets)
  • numbered lists (pound signs)
  • regular paragraphs -> please note that choosing "paragraphs" flattens the hierarchy
• supports the following output formats:
  • wikitext
  • raw HTML output (this is an export format, all wikitext - e.g. macros, widgets - is rendered first)
• supports sub-tree (branches) exports (using the node context menu or the keyboard shortcuts)
• exports the root node's text if it exists
• wraps complex nodes inside <div> tags, supporting complex streams such as Stream's FAQ and Stream's working with streams tiddlers well (see Technical details below)
  • -> please note that choosing the "paragraphs" list format does not need to wrap complex nodes inside <div> tags

Installation

Dependencies:

First install the two prerequisite plugins (visit the page and follow the installation instructions):

• the Streams plugin (v1.2.22 or greater)
  • the recommended way to install Streams is to add the SQ plugin library, and then add the plugin through the Control Panel.
• the relink plugin.
• (optional) the official Markdown plugin for TiddlyWiki can be installed. This will be useful to render new markdown tiddlers correctly, when choosing the "markdown" output format.

Installation steps:

• install the streams-fusion plugin
  • the recommended way to install streams-fusion is to add through the SQ plugin library, using the Control Panel
• between version 0.0.9 and 0.0.13, the plugin includes a javascript-based markdown conversion component. From 0.0.14 onwards, however, that functionality was removed.

Usage

• to fuse a complete stream, use the the button at the bottom of the tiddler, next to the add node button.
  • 
• to fuse a portion of a stream, use the context menu of the top-most node or the keyboard shortcuts when editing a node
  • 
• Streams Fusion configuration settings can be viewed or changed at the bottom of the Streams settings configuration page, accessible through the Control Panel

Technical details

• The general case for Streams fusion is non-trivial; Streams nodes are full tiddlers and thus can include rich content (lists, tables, multi-line, headings, etc.). wikitext list items are not, fundamentally. As a result, some node tiddler content cannot be retained, unchanged, during the conversion if one aims to preserve the hierarchy intact.
• This plugin favours visual and hierarchical accuracy of the combined tiddler (except for the paragraphs list format), once rendered, over the accuracy of the wikitext from exported node tiddlers. This means that HTML artefacts are introduced when the node content would break down the lists or numbered lists, for example when nodes contain multi line text. In edit mode, these complex nodes will show <div> tags. Jan's Streams-to-text addon does a better job at preserving original wikitext, at the expense of the tree structure and the rendering of complex node tiddlers. It can be considered to "flatten" the tree.
• Nodes that include locally-relevant macro code, or transclusions of local fields/tags will not fuse well, generally. The context of the tiddler changes after fusion, and wikitext code that relies on the context will likely not behave as expected. For example, the title of a node tiddler will change, once merged into a single tiddler (either into new name, or the name of the root tiddler). Stream nodes fields are not be preserved in the fusion.
• The approach of using the space-space-newline plugin and replacing newlines within node tiddlers with space-space-newlines within list items, instead of wrapping in <div> tags was explored, but results were unsatisfactory: for example, block rules such as headings work well in a node tiddler but were not processed when in a list item.

FAQ

• What happened to the markdown output format? Starting with version 0.0.14, the feature was removed. Instead, we recommend you install cdaven's Markdown Export Plugin. Once that is installed, the best approach is to fuse the streams to wikitext into a new tiddler, then export the new tiddler to markdown. In the future, we hope to offer the conversion as a single step and offer options to copy to clipboard or to a new tiddler directly. These options went away with this new approach.

Roadmap

• leverage cdaven's Markdown Export Plugin for conversions internal to TiddlyWiki (without having to export)

Credits

• Jeremy and the developer community for TiddlyWiki; for the enduring resolve to maintain this superb note-taking tool.
• Saq Imtiaz for the revolutionary Streams plugin, taking TiddlyWiki to new heights, and his overall community involvement.
• Jan's Streams-to-text addon for the css styles and the inspiration how to approach the merging of Streams tiddlers.
• https://www.freepik.com/ for the streams-fusion icon. Jan's icon is still nicer, but he claimed it first.
• The relink plugin for a set of features we now can't live without.
• The Tinka plugin packager; Streams-fusion was packaged without a node.js TiddlyWiki server.
• The Turndown library for markdown conversion, and the Typewriter plugin to understand how to integrate it into TiddlyWiki.

this is a demonstration stream

test