Syntaxy Example

Small

Syntaxy is very small and doesn't require extensions or additional syntax files for specific languages and comes in at around 15k minified.

Fast

Syntaxy uses a set of carefully crafted regular expression filters to quickly go through and highlight the code without DOM manipulations.

Pretty

Syntaxy's main stylesheet file is written in Sass and uses variable files to control the main appearance and highlighted syntax colors.

Flexible

Syntaxy does not rely on anything else to work, but allows you to add your own regex filters or override the included filters to suit your needs.

How to Use Syntaxy

Using Syntaxy is really simple. Once you have downloaded the project files from the Syntaxy github repository, either manually or using a package manager, start by including the Syntaxy theme CSS file to handle the appearance, and the Syntaxy Javascript file to handle the functionality. These are located in the /dist folder.

You can initialize Syntaxy by creating a new instance of it: var syntaxy = new Syntaxy( target, options );, or if you have jQuery already loaded, use it as a plugin: $( '.targets' ).syntaxy( options );

The options tell Syntaxy how to highlight the code for the selected target element, among other things, and can be passed to the Syntaxy constructor, or be read from the target element's data attributes, or a combination of both.

                        <!DOCTYPE html>
                        <html>
                        <head>
                            <title>Example Page</title>
                            <link rel="stylesheet" href="/path/to/syntaxy.theme.min.css" />
                        </head>
                        <body>
                            <pre id="syntaxy" data-type="markup">
                                code to highlight here...
                            </pre>
                            <script src="/path/to/syntaxy.min.js"></script>
                            <script type="text/javascript">
                                var target  = document.getElementById( 'syntaxy' );
                                var syntaxy = new Syntaxy( target, {} );
                                syntaxy.render();
                            </script>
                        </body>
                        </html>

Syntaxy Options

There are different ways to pass options to Syntaxy, one way is to pass it to the Syntaxy constructor during instantiation, or using the setOptions( options ); method.

                        // pass options to constructor
                        var syntaxy = new Syntaxy( target, { codeType: 'default' } );
                        // or, use the setOptions method
                        syntaxy.setOptions( { codeType: 'default' } );

Another way is to pass options to Syntaxy is by using data attributes on the target element that holds the code to be highlighted. Note that only some options can be passed using data attributes, see the options table below for more info.

                        <pre class="syntaxy" data-type="default" ...>
                            code to highlight here...
                        </pre>

Extending Syntaxy Filters

You can create your own Regular Expression filters (functions) that extend the built-in Syntaxy filters. Start by setting the data-type attribute of your container to the name of your custom filter:

                        <pre class="syntaxy" data-type="myfilter">
                            // code to highlight using myfilter...
                            foo( bar );
                        </pre>

The addFilter( name, filter ) method takes the name of your custom filter and a function that is executed in the scope of the Syntaxy class, giving you access to other methods to use. This function takes the entire code from the target container as a string and expects you to return it back out after applying your changes.

The wrapClass( class, code, strip, multiline ) method is used to wrap something, like the resulting match of a regular expression in a class that corresponds with the color (CSS theme) to be applied (highlight). This method takes the name of the CSS class (without prefix, see options), the content to be wrapped and two other boolean options, and returns the content wrapped in special tags with the defined class name.

You can use a filter that has been added to, or comes with Syntaxy by using the applyFilter( name, code ) method. This method takes the name of the filter to be used, the code string, and passes it through the filter's callback function, as described above.

                        var syntaxy = new Syntaxy( target, {} );

                        // adding a custom filter
                        syntaxy.addFilter( 'myfilter', function( code )
                        {
                            // custom code modifications for this filter
                            code = code.replace( /(foo)/g, this.wrapClass( 'function', '$1' ) );
                            code = code.replace( /(bar)/g, this.wrapClass( 'keyword', '$1' ) );

                            // apply some filters already added
                            code = this.applyFilter( 'comments', code );
                            code = this.applyFilter( 'strings', code );

                            // done
                            return code;
                        });
                        // render final markup (highlight)
                        syntaxy.render();

Building Syntaxy

Syntaxy already comes with a few themes compiled and ready to go out of the box, but you can also build your own themes from the included source files in the /src folder.

You will need Node JS installed and be familiar with using Gulp tasks to build and minify both the CSS and Javascript code. Here's a few examples of how to use the included Gulp tasks to build Syntaxy.

Build output (JS/CSS) can be found in the /dist folder.

                        // get the dependencies installed
                        $ npm install
                        // build and minify just the CSS to /dist
                        $ gulp build_css
                        // build and minify just the JS to /dist
                        $ gulp build_js
                        // build and minify both JS and CSS to /dist
                        $ gulp build
                        // watch both JS and CSS for changes and build both
                        $ gulp watch

Limitation of Syntaxy

Syntaxy handles the code to highlight as a string, passing it to filters to be processed. This is fast, but might cause conflicts between filters, if creating custom ones. It tries to get around this by first wrapping highlighted code in a special tag prior to rendering the code to final HTML tags.
Syntaxy's simplicity helps it work well in most browsers, but there is no support for IE 8. It has been tested to work properly on IE 9+ and should work on other browsers as well.
You tell me, submit an issue to the Github repo if you find a problem and it will get looked at.

Error Handling

Syntaxy will try to render the selected code syntax using the filter/s specified, but in case of an error, it will capture the error and default to showing the raw code as is.

You should see an exclamation symbol in the header of a Syntaxy container indicating there has been an error. When clicked, it should alert the error message for debugging, example:

                        // highlight me!