Header offset setting

[sjmeverett]

I'm writing a page which displays articles and consists of a page title as H1, and then the article content translated from markdown. I'd like to be able to start the header numbering of the content at H2, so I've made this fork. This is related to #102, but I prefer my implementation. There is an open issue for this feature here: #117

[sjmeverett]

I think I should have made a new branch and committed it to that instead... first pull request, sorry!

[michelf]

I'm not at all convinced this should be part of the Markdown parser. There's no need for it to be there. You can achieve the same perfectly well with a second filter like this one:

function shiftHeaders($text,$level)
{
    if ($level > 0)
    {
         $text = preg_replace(
            "!(</?h)([1-6])(>|\\s)!ie",
            "'\\1'.(\\2+$level >= 6 ? 6 : \\2+$level).'\\3'",
            $text);
    }
    return $text;
}

It also has the advantage that i'll continue to work if you switch to another parser or text format.

[sjmeverett]

I should think it would be a common enough use case to be explicitly supported, and the workaround seems a bit hacky to me, but I'll go with it. Thank you for suggesting the code.

[Arrvi]

I think it should be supported. I made almost identical modification to this script few months ago. It is needed. It may be more common case (part of page) than creating whole page this way.

[jjok]

Maybe a way of adding html sections would be better? Then you could use h1s all down the page.

[Arrvi]

As an option it would be great, but is there anybody, who want to write it? I bet this modification will take more than 3 lines, which is what header_offset took.

[sjmeverett]

What do you mean @jjok?

[jjok]

@stewartml Heading tags work differently in HTML5 from previous versions. Have a look at these:

http://www.w3.org/TR/2011/WD-html5-author-20110809/the-h1-h2-h3-h4-h5-and-h6-elements.html
http://www.w3.org/TR/2011/WD-html5-author-20110809/headings-and-sections.html

Actually, if you just rendered your article inside an article tag, won't that solve the problem without any changes to Markdown?

[Arrvi]

That's right. Didn't think about it. But still HTML5 is working draft and we should consider this in HTML4.01, so article, section and header tags aren't the solution.

[sjmeverett]

@jjok Ah, right. I already render the article inside an article tag, but the article title isn't in the markdown content, and is inside the article tag. Chucking the article title inside a header tag could work though, and to be honest there's no real reason why my blog engine has to ask for a separate title anyway.

On reflection, there probably isn't actually a need for this feature, as translated markdown could always be written into section elements or whatever by the page that outputs them.

@Arrvi I think it's safe to use HTML5...

[jjok]

@stewartml If you've got your code so it's:

<h1>Page Title</h1>
<article>
    <!-- Your markdown file starts here -->
    <h1>Your Article Title</h1>
    <p>article content...</p>
    <!-- Your markdown file ends here -->
</article>

... then you should be fine.

[michelf]

For my own blog I'm using the shiftHeaders function I posted above. It works great considering that some older posts are in Textile and even older posts are directly written in HTML. If I use another text format in the future it'll work fine with it without me having wire in the functionality into the newer converter. I'm quite unconvinced this functionality belongs into the Markdown parser. It's so much less trouble to keep it external.

[sjmeverett]

@jjok In my case, when you write an article you provide the title and then the markdown content, so the title is separate from the markdown but is still part of the article, so that's what I was talking about. Thanks, though.

@michelf I pretty much agree with you now to be honest :)

[vagari]

@Arrvi "working draft" is meaningless. HTML5 is usable right now across the board. And is fully backward compatible. An old browser doesn't stop working if you're using HTML5. In this scenario I'm with @jjok, but I'd like to see more HTML5 support across the board. You don't necessarily need the article element or anything, but things like section and even more so figure would be nice to have.

[jjok]

@Arrvi +1

[lukasoppermann]

@michelf I changed your function to use preg_replace_callback. But you said using is as a filter. I was wondering if this was just because of how it works (but you run it through markdown first and run the fn on the result) or if there actually is some kind of filter system for this class, where you can add filters to be run? I did not find anything in the docs.

[michelf]

@lukasoppermann It's a function that takes HTML as input and returns transformed HTML as output, hence why I'm calling it a filter (usage of that term is debatable). The function itself has nothing to do with PHP Markdown.