getnikola · Apr 13, 2017 · Apr 13, 2017
Showing with 54 additions and 27 deletions.

+42 −19 docs/manual.txt

+7 −8 nikola/conf.py.in

+5 −0 nikola/nikola.py
diff --git a/docs/manual.txt b/docs/manual.txt
@@ -1948,33 +1948,53 @@ Math
 
 Nikola supports math input via MathJax (by default) or KaTeX.  It is activated
 via the math roles and directives of reStructuredText and the usual LaTeX
-delimiters (backslash-parentheses, backslash-brackets) for other input formats.
+delimiters for other input formats.
+
+Configuration
+-------------
+
+Nikola uses MathJax by default. If you want to use KaTeX (faster and prettier,
+but may not support every feature yet), set ``USE_KATEX = True`` in
+``conf.py``.
 
 To use mathematics in a post, you **must** add the ``mathjax`` tag, no matter
 which renderer you are using.  (Exception: posts that are Jupyter Notebooks are
 automatically marked as math)
 
-We **DO NOT** support the old, deprecated and error-prone ``$inline$``
-delimiters by default. If you want to use them, please add them manually,
-like this:
+By default, Nikola will accept ``\(.\)`` for inline math; ``\[.\]`` and
+``$$.$$`` for display math. If you want to use the old ``$..$`` syntax as well
+(which may conflict with running text!), you need to use special config for
+your renderer:
 
 .. code:: python
 
-    MATHJAX_CONFIG = """
-    <script type="text/x-mathjax-config">
-    MathJax.Hub.Config({
-        tex2jax: {
-            inlineMath: [ ['$','$'], ["\\\(","\\\)"] ],
-            displayMath: [ ['$$','$$'], ["\\\[","\\\]"] ],
-            processEscapes: true
-        },
-        displayAlign: 'left', // Change this to 'center' to center equations.
-        "HTML-CSS": {
-            styles: {'.MathJax_Display': {"margin": 0}}
-        }
-    });
-    </script>
-    """
+   MATHJAX_CONFIG = """
+   <script type="text/x-mathjax-config">
+   MathJax.Hub.Config({
+       tex2jax: {
+           inlineMath: [ ['$','$'], ["\\\(","\\\)"] ],
+           displayMath: [ ['$$','$$'], ["\\\[","\\\]"] ],
+           processEscapes: true
+       },
+       displayAlign: 'center', // Change this to 'left' if you want left-aligned equations.
+       "HTML-CSS": {
+           styles: {'.MathJax_Display': {"margin": 0}}
+       }
+   });
+   </script>
+   """
+
+   KATEX_AUTO_RENDER = """
+   delimiters: [
+       {left: "$$", right: "$$", display: true},
+       {left: "\\\[", right: "\\\]", display: true},
+       {left: "$", right: "$", display: false},
+       {left: "\\\(", right: "\\\)", display: false}
+   ]
+   """
+
+Inline usage
+------------
 
 Inline mathematics are produced using the reST `math` **role** or the LaTeX
 backslash-parentheses delimiters:
@@ -1997,6 +2017,9 @@ Note that some input formats (including Markdown) require using **double
 backslashes** in the delimiters (``\\(inline math\\)``). Please check your
 output first before reporting bugs.
 
+Display usage
+-------------
+
 Display mathematics are produced using the reST `math` **directive** or the
 LaTeX backslash-brackets delimiters:
 

diff --git a/nikola/conf.py.in b/nikola/conf.py.in
@@ -953,9 +953,8 @@ PRETTY_URLS = ${PRETTY_URLS}
 # Do you want a add a Mathjax config file?
 # MATHJAX_CONFIG = ""
 
-# If you are using Jupyter Notebooks, or want support for the $.$
-# syntax (not recommended due to confusion with running text!), just add this
-# one:
+# If you want support for the $.$ syntax (wihch may conflict with running
+# text!), just use this config:
 # MATHJAX_CONFIG = """
 # <script type="text/x-mathjax-config">
 # MathJax.Hub.Config({
@@ -964,20 +963,20 @@ PRETTY_URLS = ${PRETTY_URLS}
 #         displayMath: [ ['$$','$$'], ["\\\[","\\\]"] ],
 #         processEscapes: true
 #     },
-#     displayAlign: 'left', // Change this to 'center' to center equations.
+#     displayAlign: 'center', // Change this to 'left' if you want left-aligned equations.
 #     "HTML-CSS": {
 #         styles: {'.MathJax_Display': {"margin": 0}}
 #     }
 # });
 # </script>
 # """
 
-# Want to use KaTeX instead of MathJax? While KaTeX is less featureful,
-# it's faster and the output looks better.
+# Want to use KaTeX instead of MathJax? While KaTeX may not support every
+# feature yet, it's faster and the output looks better.
 # USE_KATEX = False
 
-# If you want to use the old (buggy) inline math $.$ with KaTeX, then
-# you might want to use this config.
+# KaTeX auto-render settings. If you want support for the $.$ syntax (wihch may
+# conflict with running text!), just use this config:
 # KATEX_AUTO_RENDER = """
 # delimiters: [
 #     {left: "$$", right: "$$", display: true},

diff --git a/nikola/nikola.py b/nikola/nikola.py
@@ -828,6 +828,11 @@ def __init__(self, **config):
             utils.LOGGER.warn('The moot comment system has been renamed to muut by the upstream.  Setting COMMENT_SYSTEM to "muut".')
             self.config['COMMENT_SYSTEM'] = 'muut'
 
+        # Detect manually added KaTeX CSS (#2715/#2717)
+        # TODO: remove on v8
+        if 'katex.min.css' in self.config.get('EXTRA_HEAD_DATA', ''):
+            utils.LOGGER.warn("KaTeX CSS is now added by Nikola whenever needed (if your theme supports it). Please remove katex.min.css from EXTRA_HEAD_DATA in conf.py.")
+
         # Handle old plugin names (from before merging the taxonomy PR #2535)
         for old_plugin_name, new_plugin_names in TAXONOMY_COMPATIBILITY_PLUGIN_NAME_MAP.items():
             if old_plugin_name in self.config['DISABLED_PLUGINS']: