Extended Markdown Features

[lace-wing]

I have only found markdown-it to compile and convert Markdowns. Sorry if any of the following features is actually included by other commands and please let me know.

KaTex/MathJax

This should be the most missed feature. Writing math expressions is my weekly basis. Of course it can be done in LaTex but making environments just for math formulas is tedious.

Mermaid

A powerful plotting tool which is pretty useful for Markdown notes. I'm not sure how it can be implemented on iOS, at least I failed to install node.is/npm. Yet I see apps such as Joplin have done it, so I assume it can be supported in a-Shell as well.

Marp

Converts Markdown to slides. For the same reason (node.is/npm) I wasn't able to install Marp CLI.

Markdown to PDF

markdown-it is able to convert Markdown to HTML, then we can view and print the HTML to PDF. However I would appreciate a direct, command-based conversion.

Alternatives

Using iSH for such purpose is a pain, I tried.

[holzschu]

Hi, thanks for the suggestion. I'm not sure how to install markdown-it with JS, but I see there is also a Python port: https://github.com/executablebooks/markdown-it-py which might be easier to install.

a-Shell comes with multimarkdown, mainly because it was the only Markdown converter I could find that was written in plain C: https://fletcherpenney.net/multimarkdown/

multimarkdown doesn't have all the features of markdown-it, but it can do a lot of the job.

[lace-wing]

a-Shell already has markdown-it-py 2.2.0. It is viable to write py scripts for use of extra features/plugins, however it's a great hinder as not everyone knows/enjoys py (e.g. me). The markdown-it command can only convert basic markdown for now.

Multimarkdown is an usable alternative, however it requires extra markups (HTML, which I want to avoid as a markdown writer), internet connection (which defeats the iPad's take-and-use advantage) and learning with ancient documents.

[holzschu]

I agree that multimarkdown has many shortfalls (like I said, it was the easiest markdown converter to cross-compile for iOS), but I don't understand why you say it requires an internet connection.

[lace-wing]

According to Multimarkdown's documentation (that was mentioning changes made in 3.0 while I'm using 6.6.0, "ancient documentation"), to enable MathJax, I have to setup the following metadata, link to an active MathJax installation and view the page in a web browser:

latex input:    mmd-article-header  
Title:          MultiMarkdown Math Example  
latex input:    mmd-article-begin-doc  
latex footer:   mmd-memoir-footer  
HTML header:    <script type="text/javascript"
                src="http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML">
                </script>

[lace-wing]

There is an open source iOS app that has native support to MathJax and Mermaid. Hope it helps: https://github.com/laurent22/joplin

[lace-wing]

Update: I managed to use plugins from mdit-py-plugins, some of them work, for others, I don't know if it's because of the py port or iOS port, have glitches. At least I can do the 'fundamantal' (inline KaTex, todo list, definition list, table, etc., not the 'original' features but widely supported and essential) md conversion now. Still, functionalities and advantages of native support are unmatched, while the plugins are missing features and hard to use.

[holzschu]

Hi, I've managed to install and run markdown-it.js. It required some editing of the JS code, but not much. If you have some sample markdown file that I could test, to check that everything is running correctly, that would be great.

[lace-wing]

Hi, I've managed to install and run markdown-it.js. It required some editing of the JS code, but not much. If you have some sample markdown file that I could test, to check that everything is running correctly, that would be great.

Great thanks! Markdown-it has a live demo with rich syntax, you may use its sample text and see if things are working properly in a-Shell.

[holzschu]

I've had a look at the markdown-it demo, and it works with markdown-it.js, except for the things that depend on plugins (obviously, since I only ported markdown-it itself). I'm turning to you for suggestions as to which plugins I should port:

• https://github.com/waylonflinn/markdown-it-katex or https://github.com/classeur/markdown-it-mathjax ?
• https://github.com/markdown-it/markdown-it-emoji
• https://github.com/markdown-it/markdown-it-sub
• https://github.com/markdown-it/markdown-it-sup
• https://github.com/markdown-it/markdown-it-footnote
• https://github.com/markdown-it/markdown-it-deflist
• https://github.com/markdown-it/markdown-it-abbr
• https://github.com/markdown-it/markdown-it-container
• https://github.com/markdown-it/markdown-it-ins
• https://github.com/markdown-it/markdown-it-mark
• https://www.npmjs.com/package/markdown-it-mermaid (that seems more difficult)
• marp: that seems like an entire ecosystem, not plugins for markdown-it

Should I activate all of them by default? Assuming it works, obviously.

[lace-wing]

I'll prefer MathJax over KaTex, for its better support. Speed doesn't seem to have a significant affection in a-Shell use cases. The plugins can be on by default, as they have been well adopted by modern markdown editors (tho I never saw abbr syntax being used in popular editors). Mermaid is definitely a unique selling point, but it depends on you.

Marp is a different thing, tho written in JS as well. It has been a part of my workflow, but I'm pretty okay if you don't port it.

[holzschu]

Progress report: I've got them all, except mermaid (not tried yet) and mathjax (it didn't do anything). markdown-it-katex works, but doesn't seem to access its custom fonts, which is... not good. I'm going to see what I can do here. but the HTML needs to be paired with a katex.js from the same distribution (the one in $APPDIR/node_modules/katex/dist, not the latest version from the internet...).

[holzschu]

Update: it's now available for testing in the TestFlight version: https://testflight.apple.com/join/WUdKe3f4

[holzschu]

Update: there's even the mermaid pluging working. I added a "--header" option to markdown-it.js to generate a full working HTML file and include the relevant JS and CSS files for katex and mermaid.

[holzschu]

Update: the version with markdown-it.js is now out on the AppStore (1.12.3).

[lace-wing]

Very much appreciated, will field test it when I get chance.

[lace-wing]

Update: the version with markdown-it.js is now out on the AppStore (1.12.3).

Tested on the demo and my documents, found a few problems:

• mermaid doesn't seem to work

  On a basic diagram like

  flowchart LR
      A --> B

  or whatever diagrams I tested, it throws

  <pre>Parse error on line 1:
  flowchart LR    A --> 
  ^
  Expecting 'NEWLINE', 'SPACE', 'GRAPH', got 'ALPHA'</pre>

• no syntax highlighting or visual box for codes, quotes or tables

Besides, there are 2 minor issues:

• custom container not working
• a word undefined is inserted to beginning of output files if not --header, which is kind of weird to me

Haven't tested gantt, will update later if tested.

[holzschu]

The issue with mermaid has been fixed by updating it from version 7.1.2 to version 10.6.1.

The syntax highlighting, I think is done by the CSS. There are no CSS included by default in the output generated by markdown-it. I can add one, but I'm not sure which. Maybe bootstrap.css? https://getbootstrap.com

[holzschu]

I've solved the undefined issue, added some default CSS (copied from the markdown-it demo), added syntax highlighting. The result looks much better, thank you. For the container, a problem is that the command needs to define its name (here, "warning"):

    var container = require('markdown-it-container/index.js');
    md.use(container, 'warning'); 

So, now, "warning" works but in order to add another container, the user will have to edit the command and the CSS.

[holzschu]

Hi, version 1.12.5 of a-Shell mini is available on TestFlight (https://testflight.apple.com/join/REdHww5C ) with one key change: the command is not available with the app, but it can be downloaded with "pkg install markdown-it".

The CSS, katex and mermaid code are included with the app (because they are required to display the result in internalbrowser), but the rest (100+ MB of JavaScript modules) will be downloaded on demand. That makes the app thinner (I'm a bit self-concious about the weight of the app), and also available to a-Shell mini users if they wish. A side bonus is that it will be easier for users to customize their version (add plugins, add command line options) and the debug cycle between us will also be faster.

[holzschu]

Hi, in the latest TestFlight version (both apps), I'm trying something new: continuous markdown rendering.

• update both the app (with TestFlight) and the markdown-it package (with "pkg install markdown-it")
• start markdown-viewer file.md: a HTML viewer appears with the content of the Markdown file translated to HTML.
• either open a new window (on iPad) or left-edge-swipe to go back to the terminal, edit the Markdown file.
• see how your changes are reflected in the HTML viewer. It works great both with side-by-side rendering and with edge-swipe.