Wiki homepage is missing potentially helpful links

[rob-lindman]

I know what Markdown is but this product has a total lack of any documentation.

$Parsedown = new Parsedown();
echo $Parsedown->text('Hello _Parsedown_!');

Can I assume the above code will print out HTML from the Markdown?

The 'home' page on the documentation should just kind of SAY SO...

[westy92]

See the Example:

$Parsedown = new Parsedown();

echo $Parsedown->text('Hello _Parsedown_!'); # prints: <p>Hello <em>Parsedown</em>!</p>
// you can also parse inline markdown only
echo $Parsedown->line('Hello _Parsedown_!'); # prints: Hello <em>Parsedown</em>!

Make special note of: prints: <p>Hello <em>Parsedown</em>!</p>

[kminchev]

You seem to lack ability to read. The README.md outlines pretty well how to use this piece of software and it also says what this is and what it does.

[rob-lindman]

I went to the website and it says ALMOST NOTHING. Then I came to GitHub, and I went to the documentation page FIRST, and it's BLANK! Now I've had more of an opportunity to DIG and look around, but A BLANK DOCUMENTATION PAGE DOES NOT MEAN I CANNOT READ. I went ahead and implemented this to see if I could figure it out, and there are some questions, one of which is how do I extend it with my own interpretation, and the documentation on that is not exceptionally clear. But, sure, kminchev, I'll use my psychic powers and limitless time from now on.

[kminchev]

What is this 'blank documentation page' you're referring to?

[westy92]

@kminchev I think @rob-lindman means https://github.com/erusev/parsedown/wiki.

At first glance, it does seem blank. I added "Please use the various page links to the right."

[kminchev]

Well, that's not the only documentation this project has.

[aidantwoods]

I think these changes resolves this?

[rob-lindman]

Well, for me, the problem was resolved the next day, when I had time to come back and look around.

What I am interested in now, and not really finding, and lacking in time to thoroughly research, is a simple explanation of how to add my own 'tag'. I am new to Markdown but I like the premise and want to use it.

I would like to add something like

!!parameter

and then be able to parse this out of markdown into html such as

<script> whatever parameter </script>

Or something similar.

Basically, as a possible example, I'd like to be able to say

!!adsensekey

And have that produce the adsense script.

If I have a template that makes sense to me I can figure that out, but I didn't see that, and yes, I was frustrated by the blank home page on the documentation.

Thanks.

[aidantwoods]

and yes, I was frustrated by the blank home page on the documentation.

While it's true that the body of the page was essentially blank, I think you may have missed the sidebar which lists all the pages?

What I am interested in now, and not really finding, and lacking in time to thoroughly research, is a simple explanation of how to add my own 'tag'.

In particular, you'll probably find the inline element example most useful under the "Creating Extensions" page.

[rob-lindman]

Well, I saw those pages, but it just wasn't a general overview that I was expecting from the front page of documentation... which it turns out was on the README. The first line of the README directed me to the documentation, the documentation was basically the big white space, and the other pages, which I looked over, were more in-depth than I was prepared for initially.

With regards to the Creating Extensions page, the structure of the PHP class makes sense, but it's not obvious from my 'new to this project' perspective how I would implement something like I described.

There's another project related to Markdown out there called MDwiki. MDwiki has a feature called Gimmicks. MDwiki gimmicks do things like allowing you to add a Disqus widget with some simple markdown. I want to do something similar to that.

What I see here on the inline element example not click in terms of what the expected format of the tag is, and does not click in terms of how I would go about making something similar.

My goal was to use markdown only to make certain aspects of my site, and so far I've wound up having to go 50 / 50 on Markdown PHP, which just means that I could have just used PHP and HTML to begin with and saved myself a headache ;)

Maybe you will figure out what I am expressing and how to make a better example. I will check back to see it, because I like Markdown and I want to be able to use it more, but I haven't found a parser that is easy to extend yet, and while the front page does make it more clear, the documentation isn't adequate to train me on how to extend this to achieve the desired result.

[aidantwoods]

Something like the following will do what you're describing for your adsense example, in the latest beta release of Parsedown (provided the id is numeric and written as {adsensekey}).

class Extension extends Parsedown
{

    function __construct()
    {
        $this->inlineMarkerList .= '{';
        $this->InlineTypes['{'][]= 'AdSense';
    }

    protected function inlineAdSense($excerpt)
    {
        if (preg_match('/^{(\d++)}/', $excerpt['text'], $matches))
        {
            return array(
                // How many characters to advance the Parsedown's
                // cursor after being done processing this tag.
                'extent' => strlen($matches[0]), 
                'element' => array(
                    'elements' => array(
                        array(
                            'name' => 'script',
                            'attributes' => array('src' => 'https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js'),
                        ),
                        array(
                            'name' => 'script',
                            'text' => '(adsbygoogle = window.adsbygoogle || []).push({'
                                . 'google_ad_client: "ca-pub-'.$matches[1].'",'
                                . 'enable_page_level_ads: true});',
                        ),
                    ),
                ),
            );
        }
    }
}

Essentially what happens is that Parsedown will hand off parsing to the inlineAdSense method giving it the text starting from its registered marker onwards (registration happens in the class constructor). You are expected to return an array containing an extent key (how many characters you consumed), an an element key which maps to an element structure. If you need to see more detail about this structure than can be gauged by this example, then see either the below examples, or the element method – which should give an idea of the keys which are supported.

To write it as !!adsensekey you'd need to adjust the regex accordingly to parse it, and the constructor would be instead:

    function __construct()
    {
        $this->InlineTypes['!'][]= 'AdSense';
    }

The first statement in the constructor is this time omitted because it is only needed for new markers (! is used in inline images so is already declared).

There is some more info about extensions in #262, and #507. I've written the above for the latest beta since that gets around some of the odd semantics around the text key containing elements (described within #507).

There's also an example of a mathjax extension in #510 if you wanted a larger example (albeit quite old), as well as an example for adding and extension for <details><summary>... style hidden HTML sections in #451.

With regards to the Creating Extensions page, the structure of the PHP class makes sense, but it's not obvious from my 'new to this project' perspective how I would implement something like I described.

Hopefully the examples above will help. However if you require an in-depth understanding of how the class works, the best place to look is in the source file: particularly looking at the implementations for the block* and inline* methods – these show how the existing markdown syntax is implemented and should serve as the best example for how to make similar things in an extension.

[rob-lindman]

Thank you! This provides the level of detail and clarification I was looking for as a good 'starting point'. There's little doubt I will have to do a little head scratching but this is an actual explanation. You might consider adding this as part of your documentation. It gives me some insight into how to implement one or more of my ideas!

[aidantwoods]

You might consider adding this as part of your documentation.

Please feel free to add anything you found helpful, the Wiki is user editable :)

[aidantwoods]

Thanks @westy92, for adding the note to the Wiki homepage :)