Attention
Version 3 is now the current version of MathJax. This document is for version 2.
The Safe extension¶
The options below control the operation of the Safe extension that
is run when you include "Safe.js"
in the extensions array of
your configuration, or include Safe
in the config=
options
when you load MathJax.js
. They are listed with their default
values. To set any of these options, include a Safe
section in your MathJax.Hub.Config()
call. For example
MathJax.Hub.Config({
Safe: {
allow: {
URLs: "safe",
classes: "safe",
cssIDs: "safe",
styles: "safe",
fontsize: "all",
require: "safe"
}
}
});
would set the fontsize
option to "all"
, and the others to
"safe"
(these are described below).
The Safe extension affects both the TeX input and MathML input jax.
- allow: { ... }
This block contains the flags that control what the Safe extension will allow, and what it will block. The flags can be set to
"all"
,"none"
, or"safe"
. When set to"all"
, no filtering is done for these values (this gives MathJax’s default behavior). When set to"none"
, these values are always filtered out. When set to"safe"
, then only some values are allowed, as described below.- URLs: "safe"
When set to
"safe"
only URL’s with protocols that are listed in thesafeProtocols
property (see below) are allowed as targets ofhref
attributes or the\href
macro. By default, these arehttp://
,https://
, andfile://
URL’s.
- classes: "safe"
When set to
"safe"
, only class names that begin withMJX-
and contain only letters, numbers, or the characters-
,_
, or.
are allowed.
- cssIDs: "safe"
When set to
"safe"
, only ID’s that begin withMJX-
and contain only letters, numbers, or the characters-
,_
, or.
are allowed.
- styles: "safe"
When set to
"safe"
, only styles taken from a predefined set of styles are allowed to be given. These are listed in thesafeStyles
property (see below).
- require: "safe"
When set to
"safe"
, only the extensions listed in thesafeRequire
property (see below) are allowed to be loaded by the\require{}
macro.
- fontsize: "all"
When set to
"safe"
, MathJax will try to limit the font size to sizes between those given by thesizeMin
andsizeMax
properties. These are .7 and 1.44 by default, which means sizes between\scriptsize
and\large
are allowed. This also filters MathMLfontsize
,mathsize
, andscriptminsize
attributes, but here,"safe"
acts as"none"
, since they are given in sizes with units, and the actual size of the units is not determined at input time (it is part of the output processing). In addition, thescriptlevel
attribute is restricted to non-negative values (so scripts can’t be made larger), and thescriptsizemultiplier
is restricted to being no larger than 1, and no less than .6.
- sizeMin: .7
This is the minimum font size (in em’s) that the TeX input jax will allow when
fontsize
is set to"safe"
above. The default is the size of\scriptsize
. Values less than this are set to this value.
- sizeMax: 1.44
This is the maximum font size (in em’s) that the TeX input jax will allow when
fontsize
is set to"safe"
above. The default is the size of\large
. Values larger than this are set to this value.
- safeProtocols: {...}
This is an object that lists the protocols that can be used in
href
attributes and the\href
macro whenURLs
is set to"safe"
above. The default issafeProtocols: { http: true, https: true, file: true, javascript: false }
Note that if a protocol doesn’t appear in the list, it is assumed to be
false
, so technically,javascript
need not have been listed, but it is given to make it explicit that it should not be allowed.
- safeStyles: {...}
This is an object that lists the style properties that can be used in MathML
style
attributes and the\style
and\bbox
macros whenstyles
is set to"safe"
in theallowed
property above. The default issafeStyles: { color: true, backgroundColor: true, border: true, cursor: true, margin: true, padding: true, textShadow: true, fontFamily: true, fontSize: true, fontStyle: true, fontWeight: true, opacity: true, outline: true }
Any style property that doesn’t appear on this list is not allowed to be entered and will be removed (silently) from the style definition.
- safeRequire: {...}
This is an object that lists the TeX extensions that can be loaded via the
\require{}
macro whenrequire
is set to"safe"
in theallowed
property above. The default issafeRequire: { action: true, amscd: true, amsmath: true, amssymbols: true, autobold: false, "autoload-all": false, bbox: true, begingroup: true, boldsymbol: true, cancel: true, color: true, enclose: true, extpfeil: true, HTML: true, mathchoice: true, mhchem: true, newcommand: true, noErrors: false, noUndefined: false, unicode: true, verb: true }
These configuration options give you a lot of control over what actions MathJax is allowed to take. It is also possible override the individual filtering functions in order to customize the filtering even further, should that be needed. See the code for the details of the function names and their definitions.