switch to dark theme

Prettify MATLAB html

prettify_MATLAB_html processes html files generated by MATLAB's publish function, adding additional features such as disclosure boxes (that can be expanded/collapsed with a mouse-click), and expand-all/collapse-all links that expand/collapse multiple disclosure boxes simultaneously. This makes the document more closely resemble "official" MATLAB help files. It also:

Contents

Installation

Files and folders

The main functionality of prettify_MATLAB_html is provided in the prettify_MATLAB_html.m file. Along with this file are the folders publish overload and prettify documentation. These folders should be placed in the same folder as prettify_MATLAB_html.m.

About the publish overload folder

This folder contains a single .m file: publish.m . The folder publish overload should only be added to the MATLAB path if you wish to overload the built-in publish function. Overloading the publish function will automatically process html files, generated when you press "Publish" on the toolbar in the Editor, with prettify_MATLAB_html.
You can also configure the Publish overload using the overloadPublish function input.

About the prettify documentation folder

This folder contains all of the documentation for prettify_MATLAB_html. You do not need to add it to the MATLAB path, but if it is on the path, that won't cause any problems.


Adding helper buttons to the Quick-Access Toolbar
Most of the features of prettify_MATLAB_html require the use of additional tags in the source .m file that is to be published.
To make adding of these tags as easy as possible, you can add buttons to the Quick-Access Toolbar. The process of adding the buttons is slightly different depending upon the version of MATLAB you are running. For any version, the action only needs to be performed once (buttons are permanently added (can be manually removed) and will stay across relaunches of MATLAB).
Click here for instructions on how to use these toolbar buttons.

Adding the Toolbar buttons in MATLAB versions 2018a and later

In MATLAB versions 2018a and later, running prettify_MATLAB_html([],[],[],true) adds eight buttons to the Quick-Access Toolbar as highlighted in the screenshot below (The Quick-Access Toolbar has been moved from the default location by right-clicking and choosing Move Toolbar > Below Toolstrip):

Adding the Toolbar buttons in MATLAB versions prior to 2018a

In MATLAB versions prior to 2018a, running prettify_MATLAB_html([],[],[],true) adds eight buttons to the Shortcuts Toolbar as shown below:


In order to access these shortcuts from the Editor, they must appear in the Quick-Access Toolbar. You should receive a message at the MATLAB commmand line asking you to restart in order to add the shortcuts to the Quick-Access Toolbar. After a restart, the shortcuts will be in the Quick-Access Toolbar as highlighted in the screenshot below (The Quick-Access Toolbar has been moved from the default location by right-clicking and choosing Move Toolbar > Below Toolstrip):


If you receive a message asking you to add them manually, you can do so by right-clicking each in turn and selecting Add to Quick Access Toolbar :


Once added to the Toolbar, you may wish to show the labels, by right-clicking on each new button in the Quick-Access Toolbar and selecting Show Label :


NOTE : Currently, the shortcuts are added to the Quick-Access Toolbar by editing MATLAB's xml preference file for the Quick-Access Toolbar. MATLAB only reads this file at launch, which is why adding the shortcuts to Quick-Access requires a restart. If anyone knows how to programmatically add buttons to the Quick-Access Toolbar in MATLAB versions prior to 2018a, please let me know.

Configure Publish overload and add Toolbar buttons with one function call

You can configure the Publish overload and add Toolbar buttons with one function call:
prettify_MATLAB_html([], [], true, true)

Upgrading from an earlier version

If you are upgrading to a new version of prettify_MATLAB_html that has new buttons for the toolbar, and you have already added the Toolbar buttons for the earlier version, you can run prettify_MATLAB_html([],[],[],true) and only the new buttons will be added.


Usage

There are five valid call syntaxes for prettify_MATLAB_html :
1. prettify_MATLAB_html(inputhtmlFile)
2. prettify_MATLAB_html(inputhtmlFile, verbose)
3. prettify_MATLAB_html([], [], overloadPublish)
4. prettify_MATLAB_html([], [], [], addCommandsToToolbar)
5. prettify_MATLAB_html([], [], overloadPublish, addCommandsToToolbar)

inputhtmlFile - specify the file to be processed
    Character vector

The name or full path of the MATLAB-generated html file to be processed. The file is automatically over-written by the processed file.

verbose - control printing of messages to MATLAB command line
    Logical

Optional input to suppress the begin and end messages that are printed to the command line when prettify_MATLAB_html is run. Set to false to suppress the messages.

overloadPublish - automatically process html files when you press the publish button
    Logical

When this input is used, the first two inputs are ignored so can be set to empty.
This is an optional input to configure an overload for MATLAB's publish function, so that when you press "Publish" in the toolbar of a MATLAB edit window, the generated HTML will automatically be processed by prettify_MATLAB_html . This only needs to be done once per MATLAB session. If you put a call to:
prettify_MATLAB_html([], [], true);
in your startup.m file, publish will get overloaded every time you run MATLAB. set overloadPublish to false to stop overloading publish.

addCommandsToToolbar - add helper buttons to Quick-Access Toolbar
    Logical

When this input is used, the first two inputs are ignored so can be set to empty.
This is an optional input that when set to true, adds helper buttons to the Quick-Access toolbar. This action only needs to be performed once (buttons are permanently added (can be manually removed) and will stay across relaunches of MATLAB )
To leave the Publish overload setting in its current state, set the third input to empty:
prettify_MATLAB_html([], [], [], true)
Alternatively, you can configure the Publish overload and add Toolbar buttons with one function call:
prettify_MATLAB_html([], [], true, true)


Custom elements to use in the source .m file

Markup "tags"

Most prettify_MATLAB_html features require the use of additional markup "tags" in the original source .m file, for example to indicate where you want the disclosure boxes. You can click on the tag names in the table below to jump to examples of what these tags do and how to use them. If you add the helper buttons to the Toolbar, you can insert the [dtls], [smry], [targetn], [jumpton], [cssClasses], [class.class-name], [scalex], and [colour#] tags using those buttons.

Tag(s) Purpose
[br] Place anywhere to introduce an HTML line break
[brx] Insert a line break with specified pixel height x ; useful for creating spacing between lines where any empty line is too large a gap.
[dtls] ... [/dtls] Wrapped around a block of text will create a normally-open disclosure box around that text. These tags must be accompanied by a set of [smry] ... [/smry] tags (see below).
[smry] ... [/smry] These wrap around text inside a [dtls] ... [/dtls] block. The text wrapped in the [smry] ... [/smry] block is always displayed, regardless of the state of the disclosure arrow. The opening [smry] tag must immediately follow the opening [dtls] tag.
[targetn] Where n is any integer, e.g. [target1], [target14]. Used to insert a link target for in-page linking. A link to the target is created using the [jumpton] ... [/jumpto] tags (see below). Note that no closing tag is required.
[jumpton] ... [/jumpto] These wrap around any text that you wish to serve as an in-page link to a target that you have specified with a [targetn] tag
[cssClasses] ... [/cssClasses] These wrap around text where you define CSS classes that you wish to apply to other parts of the page using the [class.class-name] ... [/class] tags (see below)
[class.class-name] ... [/class] These wrap around text to which you wish to apply one of your CSS classes that are defined in the [cssClasses] ... [/cssClasses] block
[scalex] ... [/scale] Where x is any positive number, e.g [scale0.5], [scale1.2]. These wrap around text to which you would like to apply the specified scaling factor.
[colour#] ... [/colour] Where # is a six-digit hexadecimal number specifying the desired colour in RGB, e.g. [colourFF5614]. These wrap around text to which you would like to apply the specified colour.
[themesEnabled] Place this tag anywhere in your .m file to enable switching between light and dark themes. When enabled, a clickable link is provided at the top-right of the page to allow the user to select a theme (see top of this page for example). Click here for more info.
[darkAlt] ... [/darkAlt] Wrap these around any block that contains one or more images (including images that are auto-generated by code), where you wish to provide an alternative image in the case where the user selects the dark theme.

Pre-defined class for HTML tables

MATLAB's publish allows you to insert html markup into the source .m file. One possible use for this is to create an HTML table. prettify_MATLAB_html defines a table style class in the html file's CSS header, to format tables similarly to those found in "official" MATLAB help documents. The style class is called "MATLAB-Help". Click here to see example usage.


Examples:

These examples show how to use the tags in the source .m file, and show the resulting rendered html once published with MATLAB and subsequently processed by prettify_MATLAB_html .

Using [brx] tags

If you need to create a gap between lines, but feel adding an extra line creates too-wide spacing (e.g.):
Source in .m file:

% |The quick brown fox jumps over the lazy dog.|
%
% |How vexingly quick daft zebras jump!|

Result when converted to html:
The quick brown fox jumps over the lazy dog.

How vexingly quick daft zebras jump!

You can use the [brx] tag to create an x-pixel gap between the lines (creating a 5-pixel gap in this example):
Source in .m file:

% |The quick brown fox jumps over the lazy dog.| [br5]
% |How vexingly quick daft zebras jump!|

Result:
The quick brown fox jumps over the lazy dog.
How vexingly quick daft zebras jump!

Basic [dtls] and [smry] example

Source in .m file:

% [dtls][smry] *|.FigureColour|* [br]     _Four-element vector of double_ [/smry]
% This sets the colour of the figure, in normalised RGB.[/dtls]

Result:

.FigureColour
    Four-element vector of double

This sets the colour of the figure, in normalised RGB.


[dtls] and [smry] example with image

Source in .m file:

% [dtls][smry]Here is an svg image[/smry]
%
% <<https://www.dropbox.com/s/xxlu0ycmuqjl04x/my_image.svg?raw=1>>
%
% [br] (free image from <https://www.1001freedownloads.com/download/581454 here>) More text ...[/dtls]

Result:

Here is an svg image




(free image from here) More text ...


Using [dtls] and [smry] with inline code in the source .m file, including code that auto-generates images

Source in .m file:

% [dtls][smry] *In this section, I demonstrate the rand and surf functions* [/smry]
% Use the rand function to generate a matrix filled with random numbers in the range [0, 1]:
rand(3)
%%
% Use the surf function to plot 3-D data:
surf(peaks)
%%
% [/dtls]

Results:

In this section, I demonstrate the rand and surf functions

Use the rand function to generate a matrix filled with random numbers in the range [0, 1]:
rand(3)
ans =

    881.866500451810e-003    368.916546063895e-003    156.404952226563e-003
    669.175304534394e-003    460.725937260412e-003    855.522805845911e-003
    190.433267179954e-003    981.637950970750e-003    644.764536870088e-003


Use the surf function to plot 3-D data:
surf(peaks)


Create internal page links

Internal page links allow you to jump to other parts of the current page. To create a link, you need text that will act as the link (to be clicked by the user), and a target to jump to. Links are created using the [jumpton] ... [/jumpto] tags, and targets are created using the [targetn] tag.

For example:
Source in .m file:

% [jumpto1]Jump over this blank space:[/jumpto]
%
% <html>
% <br style="display:block; content:''; margin-bottom:500;"><br>
% </html>
%
% [target1]Welcome to after the blank space!


Result:
Jump over this blank space:



Welcome to after the blank space!

Making page links is particularly easy if you install the Toolbar buttons. Then, the targetn button will automatically number the targets, and the jumpton button will present a list of valid targets.

Using custom CSS classes

You can add custom CSS classes using the [cssClasses]...[/cssClasses] tags, and then apply those classes to other page content using the [class.class-name] tag.
For example:
Source in .m file:

% [cssClasses].small-pink { font-size: 80%; color: #FF00FF }
% .large-green { font-size: 150%; font-weight: bold; color: #10AA30 } [/cssClasses]
%
% [class.small-pink]This text is styled with small-pink.[/class]
% [class.large-green]This text is styled with large-green.[/class]


Result:
This text is styled with small-pink. This text is styled with large-green.

NOTES:
1. You can only have one [cssClasses] block in your .m file. This block should contain all the class definitions you wish to use.
2. You can place the [cssClasses] block anywhere; in the final .html file the CSS classes you define are added to the CSS section at the start of the page source. It is recommended that you add the [cssClasses] block either at the end of your .m file, or immediately after any introduction text in your .m file, e.g.:
Source in .m file:

%% This is the first line of the .m file, and will be the title
% This is introductory text.
%
% [cssClasses] define CSS classes here [/cssClasses]
%
%% Section 1 heading
% section 1 content
%
%% Section 2 heading
% section 2 content
%

Applying classes is particularly easy if you install the Toolbar buttons. Then, the class button will present a list of valid class names.

Using [scalex]

Wrap text whose size you wish to change with the [scalex]...[/scale] tags, where x is a positive value. For example:
Source in .m file:

% This text is normal. [scale1.2]This text is larger[/scale]. [scale0.8]This text is smaller[/scale]


Result:
This text is normal. This text is larger. This text is smaller

To apply scaling to a list, the [scalex]...[/scale] tags must appear immediately before and after the list:
Source in .m file:

% [scale1.2]This text is larger.
%
% * But the list
% * is not
%
% [/scale]


Result:
This text is larger.

Source in .m file:

% [scale1.2]This text is larger.[/scale][scale1.2]
%
% * And so is
% * this list
%
% [/scale]


Result:
This text is larger.

  • And so is
  • this list


Using [colour#]

Wrap text whose colour you wish to change with the [colour#]...[/colour] tags, where # is a six-digit hexadecimal number specifying the colour in RGB.
For example:
Source in .m file:

% [colourFF0000]This text is red.[/colour].


Result:
This text is red.

To apply colour to a list, the [colour#]...[/colour] tags must appear immediately before and after the list:
Source in .m file:

% [colourFF0000]This text is red.
%
% * But the list
% * is not
%
% [/colour]


Result:
This text is red.

Source in .m file:

% [colourFF0000]This text is red.[/colour][colourFF0000]
%
% * And so is
% * this list
%
% [/colour]


Result:
This text is red.

  • And so is
  • this list

Applying a colour is particularly easy if you install the Toolbar buttons. Then, the colour button will present a colour-picker for you to select your desired colour.

More information about themes

If you enable switching between themes using the [themesEnabled] tag, the page will load in the light theme by default, and the user can switch to the dark theme. If cookies are enabled on the web browser, the user's choice will be remembered the next time the page is loaded.

prettify_MATLAB_html provides two CSS classes to easily hide and show items according to the selected theme:

  1. show-if-light
  2. show-if-dark

Any item on the page that is assigned to the class "show-if-light" will be displayed if the selected theme is light, and hidden if the selected theme is dark. Conversely, any item on the page that is asigned to the class "show-if-dark" will be displayed if the selected theme is dark, and hidden if the selected theme is light. You can assign items to classes using the [class.class-name]...[/class] tag pair.

For every image that prettify_MATLAB_html finds inside a [darkAlt] ... [/darkAlt] block, it will assign that image to the "show-if-light" class, and add an "alternative" image that is assigned to the "show-if-dark" class. The name of this added image will be equal to the original image, appended by "_dark". For example, if the original image is named "image_01.png", the additional image will be named "image_01_dark.png". When the user selects the light theme, "image_01.png" is shown, and when the user selects the dark theme, "image_01_dark.png" is shown.

Adding tags using the Toolbar buttons

Once buttons have been added to the Quick-Access Toolbar, they can be used to add [dtls], [smry], [targetn], [jumpton], [cssClasses] , [class.class-name] , [scalex] , and [colour#] tags to your source .m file:

Adding [dtls] tags



Adding [smry] tags



Adding [targetn] tags



Adding [jumpton] tags



Adding [cssClasses] tags



Adding [class.class-name] tags



Adding [scalex] tags



Adding [colour#] tags



Demo of final published page



Creating a table with the "MATLAB-Help" style

Creating a simple table

Source in .m file:
% <html>
% <table class="MATLAB-Help">
% <thead><tr>
%    <th>Column 1 header</th>
%    <th>Column 2 header</th>
% </tr></thead>
%    <tr><td>one<br>The quick brown fox</td><td>two</td></tr>
%    <tr><td>three<br>Jumped over the lazy dog</td><td>four</td></tr>
% </table>
% </html>


Result:
Column 1 header Column 2 header
one
The quick brown fox
two
three
Jumped over the lazy dog
four

You can easily control the proportions of the table

With a little extra html formatting, you can set sizes of the table elements. In this case, using style="width:x%;" in the "table" tag and the first "th" tag.
Source in .m file:
% <html>
% <table class="MATLAB-Help" style="margin-top:5px; width:75%;">
% <thead><tr>
%    <th style="width:65%;">Column 1 header</th>
%    <th>Column 2 header</th>
% </tr></thead>
%    <tr><td>one<br>The quick brown fox</td><td>two</td></tr>
%    <tr><td>three<br>Jumped over the lazy dog</td><td>four</td></tr>
% </table>
% </html>


Result:
Column 1 header Column 2 header
one
The quick brown fox
two
three
Jumped over the lazy dog
four


Automatic enhancements

Try changing the width of this page to see the effects of the above.

More examples

To see more examples of usage of prettify_MATLAB_html, you can inspect the source code for this document (NOTE: link only works in MATLAB's browser, and only after installation of prettify_MATLAB_html) and also see my other FEX submission num2eng .