docpad-plugin-outputphp

Outputphp Plugin for DocPad

Quick and dirty way to preprocess with anything™ (actually markdown) and (hopfully) still get php back. This plugin operates on the extensions .html and .htm and outputs .php ,thereby reverting the html entity decoding that the Marked parser did op php tags and its content.

Sample

filename.php.html becomes filename.php with php intact. This will most likely generate a warning (Rendering the extension "html" to "php" on [file] didn't do anything.), this is normal as the php tags are unlikely to be escaped, thus no difference is created.

filename.php.html.md becomes filename.php, with markdown converted into html and php intact. The above warning will still appear if no php tags are present.

This is a quick hack with issues, do not expect much other that start debuging!

I'm sorry to dissapoint you, but it wat this or writing a custom markdown parser. Besides it worked in the particular use case it was developed for, but I decided to share it with you folks :). If you don't need the markdown functionality, you might be better of with this answer.

Known issues

Some of these issues only apply to unindented php blocks, as seen below.

• Php can't yet be served via DocPad. You should setup an traditional webserver (e.g. apache) with php enabled and make the DocPad /out directory accessible (directly or via symlink) through it.
• When using layouts, make sure you use a layout with .php.html in the extension; DocPad uses the layout extension to determine the final extension of the resource.
  • If you don't want to manage duplicate files (which defeats the purpose of layouts), you can create a symbolic link for the php layout to the html layout, like so (on linux in the layout folder): ln -s layoutname.html.eco php-layoutname.php.html.eco. Don't forget to select the appropriate layout for your (php) files!
• Html entities present in php code will be converted to their single character counterparts. There is no way in solving this issue with the currently used method. For that we would need to write a markdown parser that doesn't escape php code in the first place.
• Opening p tag disappears when php code is added at begin of paragraph with removePTags: true
  • Can possibly be solved if a sign is added that triggers removePTags: false for that particular match
• Php code cannot contain

  tags. It is this limitation or dozens of errors when using multi line php. However, html tags should appear if you manually encode them (yet another quirk).

• Any php code that matches the markdown syntax will be converted into its html counterpart, this may cause unintended behavior. At the moment I don't know what behavior is more desired, so I'm settling with the least work intensive method
• Issues with escaped characters
• Doesn't handle indention

Recommendations

Marking up your php code as a markdown code block (thus indenting, e.g. with tabs) will mitigate a lot of issues as Marked leaves code blocks untouched.

Alternatives

Solve the server issue

I haven't tried it yet, but using docpad-plugin-php in combination with dynamic: true frontmatter, might do the trick. This way DocPad should be able to serve php (you still need to have php installed, as DocPad proxies the calls)

I'm here because DocPad does not output .php extensions

You might be better off looking here: http://stackoverflow.com/questions/23710658/docpad-generate-php-output-file#26706756

Install

docpad install outputphp

Options

There is currently one option:

removePTags (default: true)

(boolean) Whether or not to remove <p> and </p> around a php tag. Note this may remove a desired tag if a php block is used at the begin or ending of a paragraph (see #known_issues).

Be more concrete please...

As with every DocPad plugin, options can be specified like this:

docpadConfig =
    # other docpad configuration...
    plugins:
        outputphp:
            # config for this plugin, yay!
            removePTags: false

To do and ideas

https://trello.com/b/nrsltIsD/docpad-plugin-outputphp

History

Discover the change history by heading on over to the HISTORY.md file.

Contribute

Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

Backers

Maintainers

These amazing people are maintaining this project:

• c0d0g3n (https://github.com/c0d0g3n)
• Benjamin Lupton [e-mail] (https://github.com/balupton)

Sponsors

No sponsors yet! Will you be the first?

Contributors

No contributors yet! Will you be the first? Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

License

Unless stated otherwise all works are:

• Copyright © c0d0g3n

and licensed under:

• The incredibly permissive MIT License