migrating from MarkDown to AsciiDoc: issues with live preview, preview layouts, commenting and include

classic Classic list List threaded Threaded
1 message Options
Reply | Threaded
Open this post in threaded view

migrating from MarkDown to AsciiDoc: issues with live preview, preview layouts, commenting and include

This post was updated on .
Dear AsciiDoc community,

Following this Tweets with Dan Allen. I’m posting my questions here hoping to get some help and advice. I’m working on a very small library prototype for serial port communication in Scilab . I used to use MarkDown but after some research I came to the conclusion that I should use AsciiDoc and it is great so far.

The requirements for my work are:

1. I want to have a mixture of working code (with C type commenting) and documentation in one place so I don’t have to update the code and documentation back and forth. (Literal programming) Basically what I have explained here.

2. I want to have modular peaces of code, and this is the basic reason I switched from MarkDown to AsciiDoc as I have explained here and here.

3. I want to have a FOSS editor with live preview. I don’t want me or my users to compile anything. Just open the document and read it through. I want it to be rendered properly in GitHub (that the platform I’m using for the moment, later maybe GitLab).

Everything seems to be OK so far, except I have some issues / questions:

1. One major issue is that the included files are shown as hyperlinks to nowhere on GitHub ( e.g. https://gist.github.com/Foadsf/seriallist.sci ):

It would be nice to have some replacement / alternative text which could be again hyperlinked to specific file in the repository using URL.

2. I have some issues with Atom live preview which I have reported here. It is just stuck on rendering and if the tree-sitter parsers disabled the collapsible parts do not work, as well as syntax highlighting. I have also reported the issue with the lack of proper vscode live preview syntax highlighting here. so far vscode seems the most reliable option due to being able to show collapsible parts properly, but lacks a proper layout.

3. As you may see in my code I am following a literal programming structure where my code is also a valid AsciiDoc. However major AsciiDoc editors vscode, Atom and AsciidocFX defy my requests to render files with other extensions rather than the ones specified. This is annoying. Is there any way to force them render other files? Preferably on vscode or atom? I have requested this feature here on Atom plugin github repo.

4. one small issue I want to be able to comment some lines inside a code block. I don't want the /* */ which I have used to comment the AsciiDoc text out.

I would appreciate if you could help me with these questions. Thanks for your support in advance.