TiddlyWiki5

Auto-generated from Jermolene/TiddlyWiki5 by Mutable.ai Auto WikiRevise

TiddlyWiki5 is an open source personal wiki system implemented in JavaScript. At its core is a tiddler system that represents wiki content as discrete content fragments called tiddlers. These tiddlers can contain text, images, links and more.

The tiddler system enables a flexible, non-linear approach to authoring content. Tiddlers can be queried, filtered and formatted using a filter syntax. They can be sequenced into narratives called storylines. Reusable logic snippets called macros allow adding blocks of wiki syntax. Custom widgets provide extensibility.

Key functionality works as follows:

The module in …/wiki.js handles representing the wiki document structure as tiddlers. Modules under …/filters implement the filter syntax for manipulating tiddler content. …/macros contains wiki macro definitions. …/parsers handle embedding content types like images and videos into tiddlers. …/widgets enables building custom UI components.

Saver modules in …/savers handle persisting tiddler content to storage backends like files. Plugins in plugins extend functionality, for example …/codemirror provides a code editor.

Testing infrastructure validates functionality. The plugin at …/jasmine integrates the Jasmine BDD framework.

Build automation, optimization and release management tools are located under bin.

At a high level TiddlyWiki works by representing wiki content as tiddler data structures that can be manipulated independently but linked together. These tiddlers are persisted and retrieved from storage backends. Functionality is added via plugins, custom widgets and macros. Testing handles validation.

References: core/modules, core/modules/filters, core/modules/macros, core/modules/parsers, core/modules/widgets

The core wiki functionality in TiddlyWiki5 is handled through the Wiki class defined in the …/wiki.js module. This class provides methods for core tasks like getting, adding, deleting, and updating tiddlers in the wiki store.

References: core/modules/story.js

The …/story.js module handles managing sequences of tiddlers into narratives through the story and history lists. It provides methods for navigating between tiddlers, retrieving and modifying the lists, and saving the updated lists.

References: core/modules/filters

Filter syntax allows querying and formatting tiddler content programmatically. The …/filters directory defines filter operators through single-function modules. This provides a consistent interface while keeping operators focused on their logic.

References: core/modules/widgets

The core functionality provided by the widget system in TiddlyWiki allows building reusable interaction components and user interface elements. Widgets define a common interface for rendering, refreshing on changes, and handling events. This provides the building blocks to construct interactive UIs from wiki syntax.

References: core/modules/widgets, core/modules/editor, plugins/tiddlywiki/codemirror

The core functionality for handling interfaces and interactivity in TiddlyWiki is provided by widgets defined in the …/widgets directory.

References: core/modules/editor, plugins/tiddlywiki/codemirror

The TiddlyWiki5 editor provides robust capabilities for editing wiki content through text operations. Key functionality is implemented in the …/editor directory and related files.

References: core/modules/savers, plugins/tiddlywiki/browser-storage

The core functionality of the TiddlyWiki5 persistence system allows saving and loading wiki documents to various storage backends. This is handled through a modular saver system defined in …/savers.

References: core/modules/savers

The …/savers directory implements saver modules for persisting wiki changes to various storage targets. Saver modules handle the task of saving wiki data and changes by encapsulating storage logic for different backends. Each saver module defines a class that implements saving functionality for a particular storage mechanism or target.

References: plugins/tiddlywiki/browser-storage

The …/browser-storage plugin handles persisting TiddlyWiki data to browser storage such as localStorage. On startup, the …/rawmarkup.js file loads any tiddlers previously saved to localStorage. It loops through each key, parses the JSON data, and either adds the tiddler object to the wiki or queues it for deletion.

References: plugins, editions/tw5.com/tiddlers

The TiddlyWiki5 codebase provides extensive mechanisms for customizing and extending the wiki functionality. The plugins directory contains plugins that can be used to add new capabilities.

References: plugins, plugins/tiddlywiki

TiddlyWiki plugins allow extending core functionality by adding new modules, macros, and widgets. The …/tiddlywiki directory contains important core plugins, including asynchronous utilities defined in the …/async.min.v1.5.0.js file. Syntax highlighting is implemented using definitions in …/files. Markdown support is added by …/wrapper.js, which leverages the Markdown-It parser.

References: TiddlyWiki5

TiddlyWiki allows tweaking options through configuration stored in tiddlers. The …/info directory contains modules for initializing information about the platform and environment. These configuration modules allow customizing TiddlyWiki behavior flexibly without modifying code. Programmers can tweak options by editing the modules stored in …/info.

References: editions/tw5.com/tiddlers

Extensions are implemented through custom parsers, widgets, and macros defined in the …/tiddlers directory. This directory contains code that extends TiddlyWiki's core capabilities.

References: editions/test, plugins/tiddlywiki/jasmine

The core functionality provided by this code is validating software through testing. Suites of automated tests are defined in the …/tests directory to thoroughly exercise components and ensure expected behavior.

References: plugins/tiddlywiki/jasmine, editions/test

The main entry point for running automated tests is the …/jasmine-plugin.js module. This module initializes the Jasmine testing environment and loads any test files tagged with "$:/tags/test-spec" into an isolated context. It then handles executing the tests in both browser and Node.js environments.

References: editions/test/tiddlers/tests

The TiddlyWiki test suite provides mechanisms for performing manual testing of functionality during development. The …/tests directory contains test cases that can be run manually to validate logic.

References: plugins/tiddlywiki/jasmine

The test infrastructure implements the core functionality for authoring and running tests. Tests are defined using the Jasmine syntax and stored as TiddlyWiki tiddler wiki pages tagged with "$:/tags/test-spec". The …/jasmine module initializes the Jasmine testing environment and loads these tiddler tests into an isolated sandbox context for execution.

References: plugins/tiddlywiki/jasmine/files

The Jasmine framework provides a Behavior-Driven Development (BDD) style framework for writing and running tests. At the core of Jasmine is the class defined in …/jasmine.js. The class is the main entry point for initializing Jasmine Core and running test suites. It handles setting up the environment, configuring test execution options, registering reporters, and executing the actual tests.

References: plugins/tiddlywiki/jasmine/run-wiki-based-tests.js

Tests are authored as wiki tiddlers that are tagged with the "test" tag. Each test tiddler contains the test "Output", the expected "ExpectedResult", and optional "Actions".

References: plugins/tiddlywiki/jasmine/jasmine-plugin.js

The …/jasmine-plugin.js file defines a plugin that allows running Jasmine tests within TiddlyWiki. It provides the ability to execute all tests tagged with "$:/tags/test-spec" through the …/jasmine plugin.

References: editions/test/tiddlers/tests

The tests in the …/tests directory provide automated validation of TiddlyWiki's core logic through isolated unit and integration tests. The tests cover a wide range of components, including parsing, tagging, utilities, widgets, filters, and more.

References: editions/test/tiddlers/tests/test-wikitext-parser.js

The file …/test-wikitext-parser.js contains extensive tests of the TiddlyWiki parser. It uses the Jasmine testing framework to define test suites that validate the parser's handling of wiki syntax like tags, macros, and inline/block elements.

References: editions/test/tiddlers/tests/test-tags.js

The …/test-tags.js file contains tests for the tagging functionality in TiddlyWiki5. It exercises the core tag filtering and ordering logic under different conditions to validate it meets expectations.

References: editions/test/tiddlers/tests/test-utils.js

The …/test-utils.js file contains unit tests for various utility functions used across TiddlyWiki5. These utility functions include:

References: bin

The TiddlyWiki codebase automates many build tasks to generate optimized assets and publish releases in a streamlined manner. Key aspects handled by the build system include building editions, plugins and languages; optimizing assets like SVGs; and publishing releases to npm.

References: bin/build-site.sh

The …/build-site.sh script automates building TiddlyWiki releases and editions. It sets environment variables like the build version, main edition path, and output directories.

References: bin/optimise-svgs.js

The …/optimise-svgs.js file optimizes SVG images in the TiddlyWiki core folder to reduce file sizes. It reads in all files with a .tid extension that may contain SVG code, and runs any SVG content through the SVGO library. SVGO contains plugins that can minify SVG code by removing unnecessary data like empty tags.

References: bin/npm-publish.sh, bin/verbump.sh

The …/npm-publish.sh and …/verbump.sh scripts handle tasks related to releasing TiddlyWiki and bumping versions.

References: core/modules/server

The TiddlyWiki server module …/server exposes an HTTP API to serve TiddlyWiki content and handle API requests. It provides a clean abstraction between authentication, authorization, routing, and request handling.

References: core/modules/server

The …/server directory contains code that handles HTTP requests and provides a server implementation for TiddlyWiki. At the core is the class defined in …/server.js. The class handles authorization for requests and has a method that orchestrates authentication, routing requests, and responding.

References: core/modules/server/authenticators

The …/authenticators directory contains authentication modules for the TiddlyWiki server. It implements different authentication mechanisms that can be selected in the server configuration.

References: core/modules/server/routes

The …/delete-tiddler.js class handles DELETE requests to /recipes/default/tiddlers/:title by removing the tiddler with the title from the URL parameter from the wiki.

References: core/modules/commands

The TiddlyWiki core codebase implements a command line interface using classes defined in the …/commands directory. This allows managing TiddlyWiki instances from the terminal.

References: core/modules/commands

The core functionality implemented in the code is the command line interface and command classes. The …/commands directory contains modules that define commands as classes. Each command is implemented as its own class.

References: core/modules/commands/build.js, core/modules/commands/clearpassword.js, core/modules/commands/commands.js, core/modules/commands/deletetiddlers.js, core/modules/commands/editions.js, core/modules/commands/fetch.js, core/modules/commands/help.js, core/modules/commands/import.js, core/modules/commands/init.js, core/modules/commands/listen.js, core/modules/commands/load.js, core/modules/commands/makelibrary.js, core/modules/commands/output.js, core/modules/commands/password.js, core/modules/commands/render.js, core/modules/commands/rendertiddler.js, core/modules/commands/save.js, core/modules/commands/savetiddlers.js, core/modules/commands/savewikifolder.js, core/modules/commands/server.js, core/modules/commands/setfield.js, core/modules/commands/unpackplugin.js

The core commands are implemented through classes in the …/commands directory. The class in …/init.js handles initializing an empty folder.