PHP markdown stack
Manual
General usage
Because the stack is PHP based, there is no markdown rendering in edit mode.
Inline markdown
This is the default mode. You enter your code in the stack exactily as if you would do in an HTML stack. It is advised to use an external markdown editor to write your code, then do a copy and paste into the stack's content.
Markdown file
To use this mode, check the "Use markdown file" option:
The file path can be the path to a local file or a distant URL. Note that you will not be able to preview the markdown file in Rapidweaver if it is a remote file. However, this should work on your published site.
If you use a remote file, it is very important to secure the access to that file. The Markdown stack has a safe mode option, which should provide an extra protection, at the price of breaking the footnote functionality. Even when using it, you should protect the access to your files for important security reasons.
You can also use a resource file as your markdown source. To do so, go to your Resources windown, right click the markdown file resource you want to use, select the Copy Macro item and paste it into the file path input field. Here is a possible workflow:
- drag and drop a blank markdown file into the resource window
- copy and paste the resource macro into the path field as described above
- switch to preview mode
- in the Resources window, right-click the mardown file and chose to edit it into the markdown editor of your choice
Each time you save the file in the editor, this is reflected into the preview. When you are satisfied, publish your page.
There is another workflow that does not involve Rapidweaver. I have used it for the presentation of the markdown stack page. In this page, the markdown is not inside a Rapidweaver project, but is stored on a server. To edit it, I use an FTP program like transmit, open the folder where the file is, and right click it to edit it on my mac. Each time I save the file in the editor, it is updated on the server. Of course, to see the changes in the browser, I have to refresh the page!
Options
Safe mode
Check this to enable some protection on your markdown content, especially if using a file source in an untrusted environment.
Quotations
You have an option to add custom styling to quotations if your theme does not handle them correctly.
Syntax highlighting
If you use our Syntax Highlighting stack, this option lets you specify a preferred language on a stack basis, instead of setting it at the page level.
Known bugs
When using the stack in inline mode, PHP crashes when there is a quote ' character. You must "escape" it, that put a backslash before the quote, like this: \'. This is probably due to the way HTML container interacts with stacks code. This bug does not occur when using a markdown file.
Acknowledgements
The stack is based on the parsedown, parsedown extra and parsedown extended PHP libraries.
