New plugin: Asciidoctor for TiddlyWiki

[bimlas]

Asciidoctor is a lightweight markup language, similar to Markdown, but way more powerfull. It's addictive: once you getting familiar with it, you cannot go back to Markdown.

"Use AsciiDoc for document markup. Really. It's actually readable by humans, easier to parse and way more flexible than XML."

Linus Torvalds

Demo + install: https://bimlas.gitlab.io/tw5-asciidoctor/

Source code: https://gitlab.com/bimlas/tw5-asciidoctor

Asciidoctor website: https://asciidoctor.org/

Asciidoctor vs Markdown: https://asciidoctor.org/docs/user-manual/#compared-to-markdown

[TonyM]

Bimlas,

Thanks for sharing. I need to evaluate if I should learn this alternate markup, it does seem to provide a richer set of choices but can you tell me a couple of things.

How does it handle page breaks especialy before you know where they will occur?

Will it display correctly in open new window such we can use the browsers print (including to pdf)?

If we use wikitext tranclusions etc.. can they be honored? Perhaps by surrounding it as a block?

Whilst the plugin will render this markup correctly would we then copy our text elsewhere to generate pdfs.

Thanks in advance but also your contribution to the tiddlywiki platform.

Tony

[Mohammad]

Great job!

Thank you bimlas!

Mohammad

[Mark S.]

The first demo & install gave me a 404 message. I'm getting errors (505, timeouts) when trying to see the readme at gitlab (the Source code link).

Hopefully gitlab will be working better later.

For now, a question ...

The reason I don't use markdown with TW is because it won't let me use widgets.

Does the same limitation apply to tw5-asciidoctor?

It's kind of a non-starter if it can't support TW widgets. I suppose if you're a writer then being able to do massive texts in AsciiDoctor would be useful even without widgets.

Thanks!

-- Mark

[Mark S.]

Answering my own question, you can't include widgets.

But I just realized that when you transclude an AsciiDoctor or Markdown tiddler, the text gets rendered appropriately. So there's better authoring possibilities there than I had previously thought. You could use a regular tiddler to present mutliple AD or MD tiddlers.

Small note: There's no tag tip on the AsciiDoctor icon out in the sidebar.

Thanks!

-- Mark

[Thomas Elmiger]

Very interesting, thanks for sharing!

One small issue: the footnote [1] in your demo opens a new empty tiddler. The old problem of intra-tiddler links is still unsolved.

Cheers, Thomas

[@TiddlyTweeter]

Ciao bimlas & all interested

I think the whole issue of support for other markup systems is very interesting. And important. Important not least because it could really expand the user-base if we had more flex on that.

I want to point out that JS library solutions MIGHT be compatible with normal TW content type. I think the issue is about "order of changes."

BJ did great work on this that illustrates its possible to have an approach that runs as a "pre-parser" and THEN selectively enable the additional rules in the normal TW content type.

Personally I only used this method to run "pre-parsing" through raw regular expressions ... That is the first pass, then there is a second pass that lets TW use its normal content type.

BJ's core work on this is here & is likely worth a look: http://bjtools.tiddlyspot.com/#Flexitype%20Demos. Its worth looking if only to better understand fundamental TW parsing.

Best wishes
Josiah  

[David Gifford]

Added this to the toolmap (https://dynalist.io/d/zUP-nIWu2FFoXH-oM7L7d9DM) under the section "Writing and editing - I need to categorize these yet"

[bimlas]

@Josiah: Thanks, I will check it out - I like the idea of "pre-parsing".

@David: Thank you very much! I did not know this list and I did not know that Tiddly has so many plugins... o_O Just found my other plugin: https://dynalist.io/d/zUP-nIWu2FFoXH-oM7L7d9DM#q=bimba - can you please rewrite my name to "bimlas" and change the description to this: "Filter by multiple tags: Use the checkboxes to filter the list of tags; clicking on the tag lists only those tiddlers that are assigned to each of the selected tags. The list can be filtered using the global search box."? Thanks!

[TonyM]

Bimlas,

None of the links to get the plugin seem to be working for me.

Regards

Tony

[bimlas]

For me, it works - but it seems that GitLab pages are unstable, maybe I has to switch back to GitHub...? :(

[TonyM]

Bimlas

Any chance you can tell me how to download the installable drag and drop version from GitHub?

Thanks in advance

[bimlas]

@TonyM

Sorry, but I'm not sure what "installable drag and drop version" means: the code, an exported tiddler, ...?

Anyway, here's the code:

https://gitlab.com/bimlas/tw5-asciidoctor

Here's a link to download the code as a ZIP file (to copy to the clone of https://github.com/Jermolene/TiddlyWiki5):

https://gitlab.com/bimlas/tw5-asciidoctor/-/archive/master/tw5-asciidoctor-master.zip

The site works for me, you can drag-n-drop the plugin from it:

https://bimlas.gitlab.io/tw5-asciidoctor/

[bimlas]

Just uploaded the HTML version to temporally solve the problem. The original site still isn't working?

https://files.fm/u/qbc5nbh8

[Mark S.]

Gitlab kept giving me 404 and 505 messages when I tried to navigate the site, but I was able to download the release zip and set it up under node. It wasn't drag-and-drop  though -- you have to set it up like a plugin.

-- Mark

[bimlas]

@Mark:

Please clarify what does "drag-n-drop installer" means? What should it contain? The contents of the plugin/bimlas/asciidoctor? If yes, where should I keep the contents of editions/asciidoctordemo? Is there a preferred way to distribute this kind (Javascript) plugin? How can I "set it up like a plugin".

I LOVE TiddlyWiki, but the development of it needs radically different techniques what I used before. Can you please give me hints about best practices?

[Mark S.]

I doubt most users of TW are using node.js Even those that are may not know how to set up plugins -- the documentation for that isn't on the user page at TiddlyWiki.com.

For ease of installation and assessment, the quickest way would be to export the plugin and post it here. After that, it would be good to have a full generated tiddlywiki page, either on gitlab or some other site, so the plugin could be dragged and dropped into another TW without the need for a node configuration.

Yes, currently there is no real central authority or distribution for TW plugins, tips and other artifacts.

-- Mark

[David Gifford]

Changes made. blessings.

[bimlas]

@Mark:

I would like to export the files pragmatically (via GitLab-CI) to be sure that all of those are generated. Creating the JSON and HTML works, but I cannot find a way to export as TID file. How can I achieve this?

.gitlab-ci.yml

image: node

pages:
  script:
    - git clone --depth 1 https://github.com/Jermolene/TiddlyWiki5 tw5
    - cp -r editions plugins tw5
    # Generate as index.html: single HTML demo page
    - node tw5/tiddlywiki.js tw5/editions/asciidoctordemo --build index
    # Generate as .json file: drag-n-drop installer for single HTML
    - node tw5/tiddlywiki.js tw5/editions/asciidoctordemo --savetiddler '$:/plugins/bimlas/asciidoctor' tw5-asciidoctor.json
    # Generate as .tid file: drag-n-drop installer for node version
    # DOES NOT WORKS - exports as JSON
    - node tw5/tiddlywiki.js tw5/editions/asciidoctordemo --savetiddler '$:/plugins/bimlas/asciidoctor' tw5-asciidoctor.tid
    # GitLab needs 'public' dirname for deploy
    # https://gitlab.com/gitlab-org/gitlab-ee/issues/1719
    - mv tw5/editions/asciidoctordemo/output public
  artifacts:
    paths:
    - public

[bimlas]

@Mark, @TonyM

Just found a way to speed up the site, can you please check if it still drops 404/505?

https://bimlas.gitlab.io/tw5-asciidoctor/

And here's the JSON "installer": https://bimlas.gitlab.io/tw5-asciidoctor/tw5-asciidoctor.json

[Mark S.]

That's much more friendly! How is the document being hosted?

-- Mark

[TonyM]

Bimlas,

Just know I got a 404 error, and then other times opened the wiki, I can view the json file but not select or download.

All a bit, odd, I do not know why I am getting different behaviours.

I have some kind of JSON viewer in FireFox and could save the file, but It will not drop on my wiki

I really am not sure what is wrong. I will restart everything and try again.

Tony

[bimlas]

@Mark:

That's much more friendly! How is the document being hosted?

Everything is the same, expect that I added Gzip compression: GitLab is not compressing by default (https://gitlab.com/gitlab-org/gitlab-ce/issues/14344) but the feature can be used by serving "manually" Gziped version of HTML (https://gitlab.com/gitlab-org/gitlab-pages/merge_requests/25).

See my modification in .gitlab-ci.yml: https://gitlab.com/bimlas/tw5-asciidoctor/commit/0b43e6b0c885e83943e80fed458dd2986f48a492

@TonyM:

Can you check https://bimlas.github.io/tw5-asciidoctor/ please? Trying to host on GitHUB instead of GitLAB - I don't know what to do: I would like to use Lab but Hub pages seems to be more reliable if it works for you.

PS: I apologize for taking your time, but it always works for me, I cannot test it. Thanks for help!

[TonyM]

Bimlas,

I dragged and dropped the plugin with no luck, as before I get an import on an untitled tiddler with the link $:/plugins/bimlas/asciidoctor there in .

However exporting the plugin from https://bimlas.github.io/tw5-asciidoctor/ to a json file, then dragging that to my wiki has installed asciidoctor.

If you did the same and placed the exported file on a host with the link in you wiki it may help, however the plugin drag and drop should work. Did you build the plugin correctly ?, it looks like you have, but.... 

Thank you also for your patience. This is an odd symptom.

Any way, now I can have a play.

Regards

Tony

[bimlas]

Finally I'm done:

Source code: https://gitlab.com/bimlas/tw5-asciidoctor

Demo page: https://bimlas.gitlab.io/tw5-asciidoctor

Download as JSON file ("File -> Save as" when loaded): https://bimlas.gitlab.io/tw5-asciidoctor/tw5-asciidoctor.json

@TonyM: I don't know why the demo page not working (Error 404), but can you check it again, please? The JSON should work fine now.

If everything is OK, then please mark this message as answer - I don't know how to do.

[armlet]

Hi @bimlas,

I installed your plugin and started to play around by referring to user manual. I found something called admonition paragraph doesn't render with the icons. 

[bimlas]

armlet,

You are right, no icons appear. On the one hand, because Font Awesome icons are basically unavailable in TiddlyWiki (you have to install them separately), but even if they were available, they would not appear due to the weakness of the plugin.

The Asciidoctor plugin is one of my first TiddlyWiki plugins and I haven't been improved it for a long time, even though it's not perfect in many ways. Please be patient, I will fix it when I have time. Thank you for your patience!