site
contact
newsLimitations of markdown
I am beginning to have doubts about markdown, for anything but the most simplest usage. Blogs, github, maybe ok, but for more complex pages, there are serious limitations.
I was porting the "How Easy works" page to markdown. This was originally written in SeaMonkey Composer, WYSIWYG HTML editor.
Due to the limitations of standard markdown syntax, as per the Daring Fireball markdown to HTML converter:
https://daringfireball.net/projects/markdown/
I had to insert actual HTML. OK, markdown allows this, and passes it through unchanged. But not quite...
First, a comment. For a reasonably-complex tutorial, here I am having to insert HTML. So, why am I not writing the whole thing in HTML, and avoid all the markdown-to-HTML conversion gotchas?
And yes, there are many gotchas.
Secondly, I was puzzled, as the markdown converter was mangling some of the HTML code. What I am doing is inserting syntax-highlighted HTML that was exported from Geany text editor.
Geany outputs lines that look like this:
<span class="style_2">###find drives###</span><br />
<span class="style_2">#find the drive we are booting on (has vmlinuz, initrd.q, q.sfs), and working drv...</span><br />
<span class="style_7">. /</span><span class="style_8">BOOT_SPECS </span><span class="style_2">#has BOOT_DISKID, BOOT_PARTNUM, BOOT_FS, BOOT_DIR, WKG_DISKID, WKG_PARTNUM, WKG_FS, WKG_DIR, Q_DISTRO_VERSION</span><br />
<span class="style_8">echo -n -e </span><span class="style_5">"\\033[1;35mFinding drives:\\033[0;39m\n " </span><span class="style_2">#purple</span><br />
<span class="style_8">CNT</span><span class="style_7">=</span><span class="style_3">0</span><span class="style_7">; </span><span class="style_8">Pb</span><span class="style_7">=</span><span class="style_6">''</span><span class="style_7">; </span><span class="style_8">Pw</span><span class="style_7">=</span><span class="style_6">''</span><span class="style_7">; </span><span class="style_8">BOOT_DRV</span><span class="style_7">=</span><span class="style_6">''</span><span class="style_7">; </span><span class="style_8">WKG_DRV</span><span class="style_7">=</span><span class="style_6">''</span><br />
<span class="style_4">while </span><span class="style_7">[ </span><span class="style_9">$CNT </span><span class="style_7">-</span><span class="style_8">lt </span><span class="style_3">8 </span><span class="style_7">];</span><span class="style_4">do </span><span class="style_2">#drives may take couple seconds to become available.</span><br />
<span class="style_8">sleep </span><span class="style_3">1</span><br />
<span class="style_8">CNT</span><span class="style_7">=$((</span><span class="style_9">$CNT</span><span class="style_7">+</span><span class="style_3">1</span><span class="style_7">))</span><br />
<span class="style_4">for </span><span class="style_8">aDRV </span><span class="style_4">in </span><span class="style_7">/</span><span class="style_8">sys</span><span class="style_7">/</span><span class="style_8">block</span><span class="style_7">/</span><span class="style_8">sd</span><span class="style_7">[</span><span class="style_8">a-z</span><span class="style_7">] /</span><span class="style_8">sys</span><span class="style_7">/</span><span class="style_8">block</span><span class="style_7">/</span><span class="style_8">mmcblk</span><span class="style_7">[</span><span class="style_3">0</span><span class="style_7">-</span><span class="style_3">9</span><span class="style_7">]</span><br />
<span class="style_4">do</span><br />
I put this inside <code></code> tags, and it is supposed to be passed through as-is, but isn't. For example, the text BOOT_DEV something WKG_DEV gets translated to BOOT<em>DEV something WKG</em>DEV.
At first glance, I thought "great", but then I noticed the mangling here and there. Reading the Daring Fireball docs:
Unlike block-level HTML tags, Markdown syntax is processed within span-level tags.
Even though the <span> tags are within a <code block makes no difference. Now the word that came to mind was "cr*p".
The problem is, there doesn't seem to be any way around it, using the Daring Fireball converter. So, googling, found that the Kramdown converter supports this:
By default, kramdown parses kramdown syntax inside span HTML tags. However, this behaviour can be configured with the parsespanhtml option. If this is set to true, then syntax parsing in HTML spans is enabled, if it is set to false, parsing is disabled.
It is also possible to set this on a per-tag basis.
So, I need to investigate alternatives to Daring Fireball. However, the first point I raised is very valid.
HTML is for everything, from the basic markup that markdown emulates, to sophisticated page layout. However, there is no difficulty in entering basic non-page-layout HTML tags when creating a page. Which does raise the fundamental question, why use markdown?
Why drop down to such a primitive syntax, when you find that anything beyond the most basic usage requires insertion of HTML anyway?
This is a valid question. I am thinking of extending shellCMS to enabled writing posts in SeaMonkey Composer. These will be raw non-page-layout HTML, to which shellCMS can add header and footer. Expect another post on this topic!
Tags: shellcms