Alternative markup like Asciidoc

Features
1

Hi,

thank you very much for your efforts, Joplin is a great tool and I appreciate it as it is.
Still I am wondering how difficult / time consuming it would be to incorporate Asciidoc(tor) into Joplin as an alternative to markdown.
It is available in Javascript: (Asciidoctor.js.

Besides my personal preference for its syntax Asciidoc has some benefits over Markdown, as it was built as a plain-text alternative to DocBook and has nice things like admonitions and inner-word markup.

Thanks,
Anansi

2 Likes
2

Joplin is really built around Markdown so alternative markups will not be supported. However it might be possible to add the features you need via markdown plugins.

3

I think OP’s question is not about specific AsciiDoc features that would be nice to have in Joplin/MarkDown. It is about dealing with notes that have other ways of representing content.

Joplin is a tool that maintains collections of notes. Notes are documents that have content, resources and metadata. Documents can be edited, displayed and converted.

There’s an editor, displayer and converter for documents with MarkDown-style content. It should be possible (note I’m not saying that it will be easy) to isolate the markdown stuff in modules, and allow other modules that handle e.g. AsciiDoc.

Again, it won’t be easy and I don’t expect it to happen overnight. But it could be a good start to ask yourself when working on the code: is this part of joplin or part of markdown?

With a pluggable editor/displayer it would even be possibile to use Joplin to maintain its own source code.

4

Yes I see what you mean but this is currently not an objective as it would be complicated to support multiple markups, and it’s not something that we do and it’s done - it’s a lot of complexity that we’ll have to deal with permanently afterwards. It’s not just rendering, there are other parts of the code that expect Markdown. For example:

  • There’s a service that index the resources used by notes - to do that we need to parse the Markdown note.
  • Likewise, there’s a TOC popup that is planned and it will be built based on the markdown text.
  • The search engine indexing most likely will need to be tweaked for each markup.
  • We could have a tool that helps creating Markdown tables.
  • When we import Markdown file, currently we just copy the text to the note. But if we support multiple markup, it would be logical to convert the MD text to the currently active markup.

Now every time we change something to these parts of the code, it will have to be updated x times, for each supported markup. There are several other examples like this. So that’s why in this case it makes sense to restrict the scope of the project to allow building other useful features.

2 Likes
5

Thank your very much for your answer. I would like to point out some abilities of Asciidoc:

  • Speaking in terms of functionality Asciidoc is a superset of Markdown, even with flavors, so with a fixed Markdown flavor it is feasible to convert from Markdown to Asciidoc
  • Asciidoc already has a TOC functionality builtin.
  • Asciidoctor (sic) has some Markdown compatibility builtin: Asciidoctor
  • Asciidoc has a defined standard, but was built to be extended, so there is no need for flavors. It is for example used by Fedora for its documentation Fedora Wiki because of its balanced nature as feature rich but easy to read/learn markup language.

None of these points invalidate yours and I was expecting your answer, especially because you did a very good job integrating Markdown. Right now I am lacking the skill to take a look at your code myself and to try to integrate Asciidoc (hence my feature request).

So in conclusion I support your decision to concentrate on other useful features.

edit:Typo

6

@laurent Your points are very valid, but still I do not agree :slightly_smiling_face:.
From software design perspective, all these functionalities can (and should) be part of the implementing backend. So in case of the AsciiDoc backend, it should provide hooks or API entries to get TOC info, search info, resource info, and so on.
This also implies that backends need not provide all functionality upon first release. And, most important, implementation and maintenance can be dealt with by other developers than the Joplin core team.
So from your perspective, you only need to maintain the MarkDown stuff. But you will have to do some restructuring of Joplin code to make a clean separation of the MarkDown dependent code. I think that would be a good thing to do anyway.

7

I see that we can have HTML as a ‘markup’ property, I wonder if it could be used to wrap asciidoctor.js?

image

8

I would love to see support for Asciidoc in Joplin. But I would advise against using HTML instead of Markdown/Asciidoc in the text files themselves. Comparing different iterations of a page might be easier and updates of the search index will scale better with Markdown/Asciidoc markup instead of verbose HTML.
Having Asciidoctor.js creating a dynamic HTML preview of Asciidoc on the other hand is exactly the scenario I had in mind for Joplin.

1 Like