https://github.com/maxgyver83/tid2md
Convert TiddlyWiki .tid files to Markdown files
https://github.com/maxgyver83/tid2md
command-line-tool markdown python tiddlywiki tiddlywiki5
Last synced: 11 months ago
JSON representation
Convert TiddlyWiki .tid files to Markdown files
- Host: GitHub
- URL: https://github.com/maxgyver83/tid2md
- Owner: MaxGyver83
- License: mit
- Created: 2022-09-24T17:31:52.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-12-02T11:13:57.000Z (over 1 year ago)
- Last Synced: 2025-04-15T11:12:22.636Z (over 1 year ago)
- Topics: command-line-tool, markdown, python, tiddlywiki, tiddlywiki5
- Language: Python
- Homepage:
- Size: 31.3 KB
- Stars: 8
- Watchers: 4
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# tid2md
Migrate your TiddlyWiki5 (Node.js version) tiddlers (`.tid` files) to Markdown tiddlers (`.md` files for markup plus `.md.meta` files for meta information).
## Markdown in TiddlyWiki
[TiddlyWiki](https://tiddlywiki.com/) uses its own [WikiText](https://tiddlywiki.com/#WikiText) markup language. While this is the natural first choice when using TiddlyWiki, it's also possible writing tiddlers in Markdown using the official [Markdown Plugin](https://tiddlywiki.com/#Markdown%20Plugin). Markdown has the advantage that it's used in many places (p.e. GitHub, GitLab, BitBucket, StackOverflow, Reddit) and is supported by many editors, parsers and other tools. When you often copy tiddlers (or parts of them) to other websites or when you edit/process your `.tid` files with tools except TiddlyWiki itself, it might make sense to write your tiddlers in Markdown or migrate those already written in WikiText to Markdown. This is what `tid2md.py` was made for.
## Installation
Just clone this repository and copy/symlink `tid2md.py` to a directory in your `$PATH`.
For example (on Linux):
```sh
cd ~/Downloads
git clone https://github.com/MaxGyver83/tid2md.git
mkdir -p ~/.local/bin
cd ~/.local/bin
ln -s ~/Downloads/tid2md/tid2md.py
cd ~
test -f tid2md.py || PATH=~/.local/bin:"$PATH"
```
## How to use tid2md.py
`tid2md.py` is a Python script to be run in a terminal. It takes a list of `.tid` files as input parameter. This means that it cannot be used with a single-HTML-file TiddlyWiki. It only works with a [Node.js TiddlyWiki](https://tiddlywiki.com/#Installing%20TiddlyWiki%20on%20Node.js) which stores every tiddler as a separate `.tid` file on your disk.
⚠ **Warning: This script was only tested by myself using my own tiddlers. Please test it on a copy of your wiki and check if the migrated tiddlers look like expected.**
### Migrate all `.tid` files:
```sh
cd path/to/wiki/tiddlers
tid2md.py --delete *.tid
```
This will create Markdown tiddlers (consisting of a `.md` and a `.md.meta` file) for all WikiText tiddlers except:
* System tiddlers
* Tiddlers containing macro definitons
* Tiddlers containing at least one table
Tiddlers with tables are skipped by default because Markdown tables are lacking many features of WikiText tables (p.e. two header rows, captions, cell alignment, cell merging, ...). Use `--tables` to migrate such tiddlers anyway.
The `--delete` option makes the script delete the original `.tid` files after a successful migration because otherwise you would end up with two versions of the same tiddler.
Run `tid2md.py --help` for more options.
## Performance
On my laptop, it takes about 370 ms to migrate 503 tiddlers (+ skipping 146 tiddlers).