/ml2jade

A tool to publish a MATLAB script to a Jade file

Primary LanguageMatlabMIT LicenseMIT

ml2jade

This tool does three things:

  • Publish a MATLAB script to a Jade file;
  • Evaluate code snippets in an existing Jade file and add the results to the original Jade;
  • Render the Jade file from either of the above to static HTML (requires Node, Jade, and Stylus)

It works like MATLAB's built-in publish function, but produces very clean Jade syntax, which can be easily combined with templates or stylesheets.

Jade files aren't meant to be viewed themselves; a tool renders them to HTML (either statically or as part of a webserver). ml2jade is useful, for instance, if you maintain a series of MATLAB examples for a website. You can write MATLAB scripts and publish them directly to Jade using your custom template, or you can write your .jade files yourself, automatically evaluate the code blocks inside of them and include the results directly in the .jade file, and then put the final files on the web server.

Examples

To publish a MATLAB script to Jade, call enjaden from within MATLAB.

enjaden('my_script.m');

This will create my_script.jade with all of the command line and figure outputs included under each section of code.

By default, the output directory will be the same directory the file is in. To specify the output directory:

enjaden('my_script.m', 'path/to/outputs');

To use a custom template for the page frame (see the included _template.jade for more):

enjaden('my_script.m', 'path/to/outputs', '_my_jade_template.jade');

When the template isn't provided or is empty ([]), it will use _template.jade.

To publish to Jade without evaluating the code (just translating the code itself):

enjaden('my_script.m', 'path/to/outputs', [], false);

Finally, the render the Jade to static HTML (requires Node, Jade, and Stylus):

enjaden('my_script.m', 'path/to/outputs', [], [], true);

Installation of ml2jade

If you're a GitHub user, you can clone ml2jade to whatever location you like. Just add this location to the MATLAB path.

If you're not a GitHub user, you can just download a copy (link at the right hand side of the page) or create a GitHub account so you can keep syncronized with updates and things. Assuming you download the file, unzip it somewhere and add that location to your MATLAB path.

Using Jade

If you already have a way to work with Jade files, there's nothing new you'll need to do here. Otherwise, you should know that Jade is a great language for making web pages. You can actually run a server that serves up Jade files or you can render .jade files down to static HTML.

Let's look at rendering to static HTML first. ml2jade can do this for you; it's the final argument to ml2jade and enjaden. You'll just need to have Node, Jade, and Stylus installed.

  1. Head on over to Node.js and download the appropriate installer for your system. Run the installer.
  2. If that worked, open a terminal window (command line) and run npm install jade -g (or sudo npm install jade -g if you get a message about permissions on OS X or Linux).
  3. Now install Stylus the same way: npm install stylus -g (or sudo npm install stylus -g).

Done! Now the render option to ml2jade and enjaden will work and will produce a static HTML page from the generated Jade files.

For an example of using ml2jade with your new Jade + Stylus installation:

  1. Open MATLAB, navigate to wherever you put ml2jade and run enjaden('enjaden_example.m', 'jade') to publish enjaden_example.m to jade/enjaden_example.jade. This will publish the MATLAB script to a Jade file in ml2jade/jade/enjaden_example.jade.
  2. To convert the Jade all the way to HTML, run enjaden('enjaden_example.m', 'jade', [], [], true) (that's file name, output directory, template [default], evaluate [default], and render). This will create ml2jade/jade/enjaden_example.html.

Using a server is a great choice too, and Harp is particularly easy. It also runs on Node.js and is light and easy to use. Here's how to get set up with using Harp for the first time:

  1. Head on over to Node.js and download the appropriate installer for your system. Run the installer.
  2. If that worked, open a terminal window (command line) and run npm install harp -g (or sudo npm install harp -g if you get a message about permissions on OS X or Linux).

That's it for installation! You can now navigate to any directory with Jade files and run harp server.

For an example of using ml2jade with your new Harp installation:

  1. Open MATLAB, navigate to wherever you put ml2jade and run enjaden('enjaden_example.m', 'jade') to publish enjaden_example.m to ml2jade/jade/enjaden_example.jade.
  2. Back in the terminal window, navigate to the ml2jade/jade directory (which was just created). Type harp server.
  3. Open up a broswer and navigate to http://localhost:9000/enjaden_example.html, and the published page should pop up.
  4. You can leave the Harp server up as long as you like. When you're done viewing Jade files, go back to the terminal window and use ctrl+c to stop the server.