Escaping Velocity constructs in Markdown document during site generation?

[Laird Nelson <lj...@gmail.com>]

I'm using the Markdown Doxia plugin to author my site documentation in
Markdown.

The particular page of content I'm using has a .vm suffix on it because I
also filter in Maven pom properties.

This combination of things turns out to need escaping all over the place.

For example, one way of doing second-level headers in Markdown is to prefix
the text with two hash signs (##).  This apparently does something
comment-ish with Velocity.

Or linking an API reference like this: [some
reference](path/to/javadoc/SomeClass.html#someMethod(String))

The parentheses around the method arguments silently disappear, probably
due to the anchor.

Various attempts with backslashes in front of the hash signs doesn't help.
 Other sites have suggested that perhaps setting variables Velocity style
would work, but they don't.

So: with this particular combination of technologies, how can I escape
Velocity-meaningful tokens that are still nevertheless processed unmolested
by Markdown?

Best,
Laird

-- 
http://about.me/lairdnelson

Re: Escaping Velocity constructs in Markdown document during site generation?

[Laird Nelson <lj...@gmail.com>]

A concrete example which I've found impossible in a .vm-suffixed Markdown
source file in src/site/markdown, which otherwise renders fine:

Hello; this is [a link I'd like to have work properly][1]

[1]: some/path/to/Class.html#someMethod(String)

The "(" and the ")" do not render in the final link.  Escaping them with \
or \\ or \\\ does not work.

Doing something thoroughly annoying like this:

#set($lparen = "(")
#set($rparen = ")")

...and then:

[1]: some/path/to/Class.html#someMethod${lparen}String${rparen}

...does not work. Nor do any variations on this particular theme, or any
that also involve backslashes.

Attempting to insert decimal entities for these characters does not work.
 And so on.

What project should I file a bug under?

Best,
Laird


On Mon, Feb 18, 2013 at 7:49 PM, Laird Nelson <lj...@gmail.com> wrote:

> I'm using the Markdown Doxia plugin to author my site documentation in
> Markdown.
>
> The particular page of content I'm using has a .vm suffix on it because I
> also filter in Maven pom properties.
>
> This combination of things turns out to need escaping all over the place.
>
> For example, one way of doing second-level headers in Markdown is to
> prefix the text with two hash signs (##).  This apparently does something
> comment-ish with Velocity.
>
> Or linking an API reference like this: [some
> reference](path/to/javadoc/SomeClass.html#someMethod(String))
>
> The parentheses around the method arguments silently disappear, probably
> due to the anchor.
>
> Various attempts with backslashes in front of the hash signs doesn't help.
>  Other sites have suggested that perhaps setting variables Velocity style
> would work, but they don't.
>
> So: with this particular combination of technologies, how can I escape
> Velocity-meaningful tokens that are still nevertheless processed unmolested
> by Markdown?
>
> Best,
> Laird
>
> --
> http://about.me/lairdnelson
>



-- 
http://about.me/lairdnelson