-
Notifications
You must be signed in to change notification settings - Fork 528
Advanced Features and Customization
I believe that MultiMarkdown works pretty well "out of the box" for the vast majority of users (of course, I'm not biased or anything...) But more advanced users will eventually start thinking about features that they wish existed. Some of these features are very specific to their own documents and style, but others are more general and would be of use to everyone.
My recommended approach is:
-
Make sure you check through the documentation on the web site (there is a search feature). An increasing number of feature requests are for things that already exist.
-
Check the MultiMarkdown discussion list to see if someone has already suggested your feature, or better yet, has already solved it.
-
Decide whether it's something you could try and do yourself, or whether you need to ask for help to accomplish it. Either way, the results can be shared on my web site to help others.
The first step in trying to customize MultiMarkdown is to figure out where in the workflow the customization needs to occur:
-
Does the MultiMarkdown perl script need to be modified to add a new syntax, or change the way the output is generated? There should be fewer and fewer necessary changes in this step as the MultiMarkdown syntax matures. Also, note that I am hesitant to add new features at this level that increase the complexity of markup. It's not impossible, but I will definitely need to be convinced it's the only way to go.
-
Can the desired feature be implemented through a modification of one of the XSLT files? XSLT is a powerful tool, and can be used to really customize the XHTML or LaTeX output from a MMD document. (Many users would likely benefit from a generic XHTML to RTF XSLT stylesheet - I have been unable to locate one that would work, and I have no need of RTF documents. This would be too much work for too little gain for me, but I am sure someone out there needs exactly this sort of tool.) Browse through the
XSLTdirectory and look to see if there is a stylesheet that could be modified to do what you want. The XSLT syntax is not that complicated, but does take some getting used to. As examples, thexhtml-toc.xsltscript parses the header tags in the XHTML output, and creates an automatic table of contents at the top of the XHTML file. Thexhtml-poetry-support.xsltfile looks for code blocks that start with[poetry]and changes them to a poetry mode, rather than code (basically removing the monospace font). -
Does the desired feature need to be implemented in a separate post-processing script? For example, for LaTeX documents I use a script called
cleancites.plthat looks for strings of multiple citations to shorten the syntax. You could easily create a script to do whatever you like and incorporate it into your work flow.
In summary, a great many features and customizations can be added to MultiMarkdown by users. I also recommend that you consider sharing any of your customizations back to the MultiMarkdown community - I am happy to put any files or links on my site, if you are interested.
Again, places to look for inspiration:
-
MultiMarkdown/bin - this is where the "glue" scripts live that manage different MultiMarkdown workflow patterns. You can create your own shell scripts that can add additional steps to your workflow here.
-
MultiMarkdown/Utilities - a couple of utility scripts and the
cleancites.plpost-processing script live here; you can add files here and incorporate them into your work flow. -
MultiMarkdown/XSLT - XSLT files for modifying XHTML files or creating LaTeX files go here. Lots of examples for different styles of output or customizing the way various features work.
-
http://fletcherpenney.net/multimarkdown/xslt_files/ - this is where I will place various user submitted files that may be of interest, or offer a starting point for further customization. Please consider submitting your own improvements here as well.