math.py 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353
  1. # -*- coding: utf-8 -*-
  2. """
  3. Math Render Plugin for Pelican
  4. ==============================
  5. This plugin allows your site to render Math. It uses
  6. the MathJax JavaScript engine.
  7. For markdown, the plugin works by creating a Markdown
  8. extension which is used during the markdown compilation
  9. stage. Math therefore gets treated like a "first class
  10. citizen" in Pelican
  11. For reStructuredText, the plugin instructs the rst engine
  12. to output Mathjax for all math.
  13. The mathjax script is by default automatically inserted
  14. into the HTML.
  15. Typogrify Compatibility
  16. -----------------------
  17. This plugin now plays nicely with Typogrify, but it
  18. requires Typogrify version 2.07 or above.
  19. User Settings
  20. -------------
  21. Users are also able to pass a dictionary of settings
  22. in the settings file which will control how the MathJax
  23. library renders things. This could be very useful for
  24. template builders that want to adjust the look and feel of
  25. the math. See README for more details.
  26. """
  27. import os
  28. import sys
  29. from pelican import signals, generators
  30. try:
  31. from bs4 import BeautifulSoup
  32. except ImportError as e:
  33. BeautifulSoup = None
  34. try:
  35. from . pelican_mathjax_markdown_extension import PelicanMathJaxExtension
  36. except ImportError as e:
  37. PelicanMathJaxExtension = None
  38. def process_settings(pelicanobj):
  39. """Sets user specified MathJax settings (see README for more details)"""
  40. mathjax_settings = {}
  41. # NOTE TO FUTURE DEVELOPERS: Look at the README and what is happening in
  42. # this function if any additional changes to the mathjax settings need to
  43. # be incorporated. Also, please inline comment what the variables
  44. # will be used for
  45. # Default settings
  46. mathjax_settings['auto_insert'] = True # if set to true, it will insert mathjax script automatically into content without needing to alter the template.
  47. mathjax_settings['align'] = 'center' # controls alignment of of displayed equations (values can be: left, right, center)
  48. mathjax_settings['indent'] = '0em' # if above is not set to 'center', then this setting acts as an indent
  49. mathjax_settings['show_menu'] = 'true' # controls whether to attach mathjax contextual menu
  50. mathjax_settings['process_escapes'] = 'true' # controls whether escapes are processed
  51. mathjax_settings['latex_preview'] = 'TeX' # controls what user sees while waiting for LaTex to render
  52. mathjax_settings['color'] = 'inherit' # controls color math is rendered in
  53. mathjax_settings['linebreak_automatic'] = 'false' # Set to false by default for performance reasons (see http://docs.mathjax.org/en/latest/output.html#automatic-line-breaking)
  54. mathjax_settings['tex_extensions'] = '' # latex extensions that can be embedded inside mathjax (see http://docs.mathjax.org/en/latest/tex.html#tex-and-latex-extensions)
  55. mathjax_settings['responsive'] = 'false' # Tries to make displayed math responsive
  56. mathjax_settings['responsive_break'] = '768' # The break point at which it math is responsively aligned (in pixels)
  57. mathjax_settings['mathjax_font'] = 'default' # forces mathjax to use the specified font.
  58. mathjax_settings['process_summary'] = BeautifulSoup is not None # will fix up summaries if math is cut off. Requires beautiful soup
  59. mathjax_settings['force_tls'] = 'false' # will force mathjax to be served by https - if set as False, it will only use https if site is served using https
  60. mathjax_settings['message_style'] = 'normal' # This value controls the verbosity of the messages in the lower left-hand corner. Set it to "none" to eliminate all messages
  61. # Source for MathJax
  62. mathjax_settings['source'] = "'//cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'"
  63. # Get the user specified settings
  64. try:
  65. settings = pelicanobj.settings['MATH_JAX']
  66. except:
  67. settings = None
  68. # If no settings have been specified, then return the defaults
  69. if not isinstance(settings, dict):
  70. return mathjax_settings
  71. # The following mathjax settings can be set via the settings dictionary
  72. for key, value in ((key, settings[key]) for key in settings):
  73. # Iterate over dictionary in a way that is compatible with both version 2
  74. # and 3 of python
  75. if key == 'align':
  76. try:
  77. typeVal = isinstance(value, basestring)
  78. except NameError:
  79. typeVal = isinstance(value, str)
  80. if not typeVal:
  81. continue
  82. if value == 'left' or value == 'right' or value == 'center':
  83. mathjax_settings[key] = value
  84. else:
  85. mathjax_settings[key] = 'center'
  86. if key == 'indent':
  87. mathjax_settings[key] = value
  88. if key == 'show_menu' and isinstance(value, bool):
  89. mathjax_settings[key] = 'true' if value else 'false'
  90. if key == 'message_style':
  91. mathjax_settings[key] = value if value is not None else 'none'
  92. if key == 'auto_insert' and isinstance(value, bool):
  93. mathjax_settings[key] = value
  94. if key == 'process_escapes' and isinstance(value, bool):
  95. mathjax_settings[key] = 'true' if value else 'false'
  96. if key == 'latex_preview':
  97. try:
  98. typeVal = isinstance(value, basestring)
  99. except NameError:
  100. typeVal = isinstance(value, str)
  101. if not typeVal:
  102. continue
  103. mathjax_settings[key] = value
  104. if key == 'color':
  105. try:
  106. typeVal = isinstance(value, basestring)
  107. except NameError:
  108. typeVal = isinstance(value, str)
  109. if not typeVal:
  110. continue
  111. mathjax_settings[key] = value
  112. if key == 'linebreak_automatic' and isinstance(value, bool):
  113. mathjax_settings[key] = 'true' if value else 'false'
  114. if key == 'process_summary' and isinstance(value, bool):
  115. if value and BeautifulSoup is None:
  116. print("BeautifulSoup4 is needed for summaries to be processed by render_math\nPlease install it")
  117. value = False
  118. mathjax_settings[key] = value
  119. if key == 'responsive' and isinstance(value, bool):
  120. mathjax_settings[key] = 'true' if value else 'false'
  121. if key == 'force_tls' and isinstance(value, bool):
  122. mathjax_settings[key] = 'true' if value else 'false'
  123. if key == 'responsive_break' and isinstance(value, int):
  124. mathjax_settings[key] = str(value)
  125. if key == 'tex_extensions' and isinstance(value, list):
  126. # filter string values, then add '' to them
  127. try:
  128. value = filter(lambda string: isinstance(string, basestring), value)
  129. except NameError:
  130. value = filter(lambda string: isinstance(string, str), value)
  131. value = map(lambda string: "'%s'" % string, value)
  132. mathjax_settings[key] = ',' + ','.join(value)
  133. if key == 'mathjax_font':
  134. try:
  135. typeVal = isinstance(value, basestring)
  136. except NameError:
  137. typeVal = isinstance(value, str)
  138. if not typeVal:
  139. continue
  140. value = value.lower()
  141. if value == 'sanserif':
  142. value = 'SansSerif'
  143. elif value == 'fraktur':
  144. value = 'Fraktur'
  145. elif value == 'typewriter':
  146. value = 'Typewriter'
  147. else:
  148. value = 'default'
  149. mathjax_settings[key] = value
  150. return mathjax_settings
  151. def process_summary(article):
  152. """Ensures summaries are not cut off. Also inserts
  153. mathjax script so that math will be rendered"""
  154. summary = article._get_summary()
  155. summary_parsed = BeautifulSoup(summary, 'html.parser')
  156. math = summary_parsed.find_all(class_='math')
  157. if len(math) > 0:
  158. last_math_text = math[-1].get_text()
  159. if len(last_math_text) > 3 and last_math_text[-3:] == '...':
  160. content_parsed = BeautifulSoup(article._content, 'html.parser')
  161. full_text = content_parsed.find_all(class_='math')[len(math)-1].get_text()
  162. math[-1].string = "%s ..." % full_text
  163. summary = summary_parsed.decode()
  164. article._summary = "%s<script type='text/javascript'>%s</script>" % (summary, process_summary.mathjax_script)
  165. def configure_typogrify(pelicanobj, mathjax_settings):
  166. """Instructs Typogrify to ignore math tags - which allows Typogrify
  167. to play nicely with math related content"""
  168. # If Typogrify is not being used, then just exit
  169. if not pelicanobj.settings.get('TYPOGRIFY', False):
  170. return
  171. try:
  172. import typogrify
  173. from distutils.version import LooseVersion
  174. if LooseVersion(typogrify.__version__) < LooseVersion('2.0.7'):
  175. raise TypeError('Incorrect version of Typogrify')
  176. from typogrify.filters import typogrify
  177. # At this point, we are happy to use Typogrify, meaning
  178. # it is installed and it is a recent enough version
  179. # that can be used to ignore all math
  180. # Instantiate markdown extension and append it to the current extensions
  181. pelicanobj.settings['TYPOGRIFY_IGNORE_TAGS'].extend(['.math', 'script']) # ignore math class and script
  182. except (ImportError, TypeError) as e:
  183. pelicanobj.settings['TYPOGRIFY'] = False # disable Typogrify
  184. if isinstance(e, ImportError):
  185. print("\nTypogrify is not installed, so it is being ignored.\nIf you want to use it, please install via: pip install typogrify\n")
  186. if isinstance(e, TypeError):
  187. print("\nA more recent version of Typogrify is needed for the render_math module.\nPlease upgrade Typogrify to the latest version (anything equal or above version 2.0.7 is okay).\nTypogrify will be turned off due to this reason.\n")
  188. def process_mathjax_script(mathjax_settings):
  189. """Load the mathjax script template from file, and render with the settings"""
  190. # Read the mathjax javascript template from file
  191. with open (os.path.dirname(os.path.realpath(__file__))
  192. + '/mathjax_script_template', 'r') as mathjax_script_template:
  193. mathjax_template = mathjax_script_template.read()
  194. return mathjax_template.format(**mathjax_settings)
  195. def mathjax_for_markdown(pelicanobj, mathjax_script, mathjax_settings):
  196. """Instantiates a customized markdown extension for handling mathjax
  197. related content"""
  198. # Create the configuration for the markdown template
  199. config = {}
  200. config['mathjax_script'] = mathjax_script
  201. config['math_tag_class'] = 'math'
  202. config['auto_insert'] = mathjax_settings['auto_insert']
  203. # Instantiate markdown extension and append it to the current extensions
  204. try:
  205. pelicanobj.settings['MD_EXTENSIONS'].append(PelicanMathJaxExtension(config))
  206. except:
  207. sys.excepthook(*sys.exc_info())
  208. sys.stderr.write("\nError - the pelican mathjax markdown extension failed to configure. MathJax is non-functional.\n")
  209. sys.stderr.flush()
  210. def mathjax_for_rst(pelicanobj, mathjax_script):
  211. """Setup math for RST"""
  212. pelicanobj.settings['DOCUTILS_SETTINGS'] = {'math_output': 'MathJax'}
  213. rst_add_mathjax.mathjax_script = mathjax_script
  214. def pelican_init(pelicanobj):
  215. """
  216. Loads the mathjax script according to the settings.
  217. Instantiate the Python markdown extension, passing in the mathjax
  218. script as config parameter.
  219. """
  220. # Process settings, and set global var
  221. mathjax_settings = process_settings(pelicanobj)
  222. # Generate mathjax script
  223. mathjax_script = process_mathjax_script(mathjax_settings)
  224. # Configure Typogrify
  225. configure_typogrify(pelicanobj, mathjax_settings)
  226. # Configure Mathjax For Markdown
  227. if PelicanMathJaxExtension:
  228. mathjax_for_markdown(pelicanobj, mathjax_script, mathjax_settings)
  229. # Configure Mathjax For RST
  230. mathjax_for_rst(pelicanobj, mathjax_script)
  231. # Set process_summary's mathjax_script variable
  232. process_summary.mathjax_script = None
  233. if mathjax_settings['process_summary']:
  234. process_summary.mathjax_script = mathjax_script
  235. def rst_add_mathjax(content):
  236. """Adds mathjax script for reStructuredText"""
  237. # .rst is the only valid extension for reStructuredText files
  238. _, ext = os.path.splitext(os.path.basename(content.source_path))
  239. if ext != '.rst':
  240. return
  241. # If math class is present in text, add the javascript
  242. # note that RST hardwires mathjax to be class "math"
  243. if 'class="math"' in content._content:
  244. content._content += "<script type='text/javascript'>%s</script>" % rst_add_mathjax.mathjax_script
  245. def process_rst_and_summaries(content_generators):
  246. """
  247. Ensure mathjax script is applied to RST and summaries are
  248. corrected if specified in user settings.
  249. Handles content attached to ArticleGenerator and PageGenerator objects,
  250. since the plugin doesn't know how to handle other Generator types.
  251. For reStructuredText content, examine both articles and pages.
  252. If article or page is reStructuredText and there is math present,
  253. append the mathjax script.
  254. Also process summaries if present (only applies to articles)
  255. and user wants summaries processed (via user settings)
  256. """
  257. for generator in content_generators:
  258. if isinstance(generator, generators.ArticlesGenerator):
  259. for article in generator.articles + generator.translations:
  260. rst_add_mathjax(article)
  261. #optionally fix truncated formulae in summaries.
  262. if process_summary.mathjax_script is not None:
  263. process_summary(article)
  264. elif isinstance(generator, generators.PagesGenerator):
  265. for page in generator.pages:
  266. rst_add_mathjax(page)
  267. def register():
  268. """Plugin registration"""
  269. signals.initialized.connect(pelican_init)
  270. signals.all_generators_finalized.connect(process_rst_and_summaries)