Contents
  1. Description
    1. Features
    2. Compatibility
    3. Performance
    4. Demos
    5. How it works
    6. Philosophy
    7. Suggested workflow
  2. Warnings
    1. Security
    2. Performance
    3. Caveats
  3. Newbie Documentation
    1. Markdown syntax
    2. Footnotes
    3. Internal linking and TOC
    4. Mixing HTML, Markdown and WorPress shortcodes
    5. Typography
  4. Intermediate documentation
    1. Mermaid charts
    2. Import and include external Markdown and HTML to WordPress posts
  5. Expert Documentation
    1. Jupyter notebooks, Plotly & Bokeh graphs
    2. Maths and chemical equations
    3. Code syntax highlighting
  6. Helpers
    1. Disable Markdown rendering and typography enhancements
    2. Disable table of contents page-wise
    3. Force javascript loading
    4. Figures and captions
  7. Dev/Power-user documentation
    1. Caching settings
    2. Sequence of processing

GitHub Release Date GitHub code size in bytes Donate Donate Downloads Fork

Note : this page is fully rendered through WP Scholar plugin on the latest WordPress version, which serves both as a showcase and as a documentation.

WP Scholar provides a clutter-free, direct and fast typing experience for the heavy-duty writers who type a lot every day : technical writers, engineers, analysts, journalists, researchers, scientists, etc. It supports equations, footnotes, table of contents, code highlighting, charts drawing, interactive plots and Jupyter notebooks includes, through a direct access to the Markdown and LaTeX code. Then, it refines the typography by converting arrows, quotes and fractions to proper HTML entities, and inserts unbreakable and thin spaces where they belong.

If you are a technical writer, you may feel WordPress Gutenberg editor is going backwards, in an MS Office direction : giving an overwhelming set of formatting options while making actual typing and content production really hard. Those blocks ask you to think about the layout even before having typed the content, and make you travel constantly between mouse and keyboard. More than a hassle, they put pain on your wrists and elbows.

The truth is, WordPress is turning into a better place for marketers, but is becoming a nightmare for anyone who produces content rather than cute formatting. While most technical writers have now turned toward static content generators (Hugo, Jekyll, etc.), and researchers keep writing fixed-width PDF papers (2021 much…), WP Scholar tries to make WordPress great again for you, writer.

#Description

#Features

  1. Newbie features :
    • adds support for extended Github-flavored Markdown formatting in posts, pages and comments,
    • adds support for footnotes and inline hover cards for their content,
    • adds table of contents in posts and in sidebars with a widget,
    • adds internal anchors and backlinks to headers, for quick intra-page navigation and permanent linking to inner sections,
    • enforces correct typographic rules for the current language, such as unbreakable and thin spaces where they belong, fractions, quotes, etc.
  2. Intermediate features :
    • adds support for Mermaid graphs, allowing to quickly plot charts from simplified code,
    • removes WordPress markup filtering in posts and pages, allowing scripts and advanced HTML,
    • removes media library uploads limitations, allowing SVG, HTML and JSON uploads to media library, provides a shortcode to include them in posts and pages,
    • adds support for Plotly and Bokeh interactive and self-hosted graphs, for beautiful data visualisations and analytics.
  3. Expert features :
    • adds support for LaTeX equations in posts, comments and pages, with environments, references and equations numbering,
    • adds syntax highlighting on code blocks declared with a programming language (245 languages supported),
    • imports Jupyter notebooks and include them in pages (you can even write full posts with graphs and code in Jupyter then include them).

#Compatibility

  1. Supports Typora Markdown editor output and 90 % of its features, so you can type your posts off-line in Typora editor, and copy-paste the Markdown code,
  2. Supports TinyMCE (classic WordPress editor) and Gutenberg in their code editor versions, plus Gutenberg HTML block. The visual editors are not fully supported (see why),
  3. Supports Jetpack LaTeX syntax as well as [[latex]] shortcodes,
  4. Supports [toc] shortcode that is also used by many table of content plugins (however, they cannot be enabled at the same time),
  5. Supports all shortcodes from WordPress and other plugins,
  6. Saves posts as true Markdown code, so they can be edited again as Markdown (most editors convert Markdown to HTML in browser and save HTML).

#Performance

  1. WP Scholar only loads a minified 1.6 kB CSS file on every page.
  2. The ressources to load (CSS and JS) are detected on a page-wise basis, so only the necessary ones are loaded and your home page doesn’t get bloated with useless ressources.
  3. Javascript files (Mathjax, Prism, Mermaid, Plotly, Bokeh, etc.) are loaded from cdnjs.cloudflare.com. This ensures fast loading and proper caching for any user.
  4. WP Scholar is compatible with caching plugins and tested with WP Rocket (see the configuration help).
  5. Most scripts are loaded in footer and can be loaded asynchronously for better loading time.
  6. Since WP Scholar parse Markdown at page-rendering time, this can prove heavy and slow. A caching plugin is strongly recommended.

#Demos

The following demos are real-life posts for which this plugin was initially created :

#How it works

The whole thing is designed to be as lightweight and simple as possible. There is no configuration page, just enable and start writing Markdown or LaTeX. Everything is detected automatically, and options are defined in the text editor through HTML comments tags.

#Philosophy

No obstruction. When you put your ideas into text, you want nothing to sit between you and the text, you just want the text to flow. Think about writing in your notebook… Unfortunately, Microsoft Word and WordPress Gutenberg force you to think about the layout even before starting to actually type, because they take the problem the wrong way : you need to start creating layout blocks first, then only later fill them with content. Form doesn’t adapt to content anymore, it is the other way around.

To do so, they heavily rely on mouse actions to define and edit content blocks and their properties, while actual typing happens on keyboard. So they make you travel constantly between mouse and keyboard, which makes you lose time and put your wrist and elbow at risk of musculoskeletal and nervous strain, if you repeat it daily and for long periods of time.

The best-flowing typing experience is one where you don’t have to care about layout, while typing if at all, don’t have to put your hands off the keyboard and don’t need right-click monkey business. Which means typing text as formatted code with some markup (LaTeX, HTML, XML and the likes). But markup may be a huge overhead because it is hard to read, cumbersome to type, and slow to learn.

For this reason, Markdown was invented in 2004 to deal with formatting in the less-cumbersome way as possible. It is fast to learn, fast to use, and gets later interpreted as HTML, which allows systematic styling through templates and style-sheet. It can also be used in conjunction with HTML for cases where advanced layouts are required.

So WP Scholar takes all the benefits of Markdown, extends them with LaTeX for equations, but also adds the usual WordPress shortcodes on top, for the more advanced features like media galleries. You get all the benefits of WordPress with a simple text editor and most of the bloat out of your sight.

#Suggested workflow

#Companion editor

This plugin is designed to be compatible with Typora, a cross-platform and distraction-free Markdown editor that lets you type maths, graphs, text and tables in a very efficient way, then export to all the usual formats, on Linux, Mac OS and Windows. Type in Typora, copy-paste the Markdown code to a WordPress post or import the .md file to WordPress media library and include it, and be done with it. WP Scholar will be able to translate Typora’s Markdown, equations and graphs to HTML. Typora is, so far, the best implementation of a non-obstructive typing workflow.

This workflow has several advantages :

  • Typora provides a no-distraction WYSIWYG interface, supporting even tables, maths and diagrams rendering,
  • you keep a local copy of your articles for safety and for later export to LaTeX, PDF, ePub, HTML, etc.
  • you can work offline, while commuting, travelling, or simply to cut internet distractions, with no fear of losing your work,
  • WordPress fancy content editors tend to be more and more bloated, heavy and slow as time goes by, inducing lags and CPU overuse. A local lightweight editor is all you need.

WP Scholar supports 95 % of Typora’s features, like its extended Markdown syntax, maths rendering and Mermaid graphs. Flowcharts and Sequence charts are not supported because they duplicate Mermaid’s features for little benefit.


#Dynamic workflow

You can type your posts in Markdown straight from WordPress post editor, using the code editor. Be careful, however, because both TinyMCE (classic editor) or Gutenberg (new editor) used in WYSIWYG mode convert Markdown syntax directly to HTML at typing time, in your browser. So they don’t save real Markdown. Similarly, when you switch back from their code editor to their WYSIWYG mode, they might encode important characters things into HTML and break the Markdown syntax.

In a nutshell, while TinyMCE and Gutenberg let you type some Markdown (just the simple stuff like bold, headings and italics), when you edit those posts later, what you will edit will be HTML. So you get 2 options to retain Markdown untouched :

  • with TinyMCE, always use the code editor and never go back to the visual one, especially if you use maths equations.
  • with Gutenberg, either use the code editor or an HTML block.

Notice if you edit posts first in TinyMCE code editor and later import them in Gutenberg, some characters may by converted to HTML entities in the process, which may break syntax of LaTeX and Mermaid code. For this reason, it is better to keep editing older posts in the same editor they were primarily created, or force your posts to be converted to pure HTML using HTML blocks.

#Static workflow

You can type your posts in any Markdown editor you like, online or offline, then import the Markdown file to your media library and include it in your post (see how to include external Markdown in posts).

To edit those posts later, you can connect from your computer to your web server, through FTP, mount the remote server as a local storage, and keep editing the .md files from within your local editor. You absolutely need to name the file with a .md extension so the Markdown syntax is parsed (otherwise, any other file type is not parsed).

Notice this will not store the content of your post in WordPress database, which will disable the following WordPress features :

  • internal search in posts and pages content,
  • automatic excerpt generation,
  • SEO analyse of content from third-party plugins,
  • any further content extraction/analyse.

#Warnings

#Security

This plugin enables uploading SVG, HTML, JSON, Markdown (.md) and Jupyter notebook files (.ipynb) to WordPress media library and disables the uploaded checks on such files. These files can be used to embed malicious, unfiltered, scripts, which is the reason WordPress disallows them in the first place. Unfortunately, we don’t have a choice if we want to include local Plotly/Bokeh graphs and Jupyter notebooks as pre-rendered HTML files. A security hardening plugin, like Sucuri, Wordfence, or SecuPress, is strongly advised, with double-factor authentication and malware scanners.

This plugin also disables the default WordPress XSS detection and markup removal/sanitization in posts and pages (they are still applied on comments), because it conflicts with Markdown syntax and prevent us from using legitimate scripts in-page. It means any author on your blog can add Javascript and unfiltered markup in posts, that is possibly malicious code in posts. This is a double-edged sword : more power and more responsibilities. You need to trust your blog authors, editors, and administrators to use this plugin.

#Performance

WP Scholar keeps your posts saved as Markdown in the posts database, which means they need to be parsed and interpreted before the front-end page is rendered and served to an user. To avoid re-rendering them every time a new reader comes on your page, it is advised to use caching plugins such as W3 Total Cache, Super Cache or WP Rocket (there are plenty).

WP Scholar loads only one CSS file (1.6 kB) and one JS file (2.3 kB) per page. Both are minified already. All other CSS and JS are loaded on-demand, only on the pages where they are needed. The internal javascript of WP Scholar uses plain javascript (no jQuery or other version-tied library dependency) and will work with any web browser that is not Internet Explorer 8 and more recent than 2012 or so.

Maths equations, Mermaid charts, Plotly and Bokeh interactive graphs are rendered client-side, in the visitor’s browser, by javascript libraries which produce SVG images. This guarantees that fonts and lines are properly scaled to the viewport width and are free from aliasing or blurring, since they use the real screen resolution. However, this puts a computational cost on the visitor’s device and might take some time to render on older devices. Also, SVG is supported only by fairly recent web browsers (newer than 2014).

#Caveats

#Special symbols

WP Scholar expects dollar symbols $ to enclose maths equations, like $x + y = z$ or $ x + y = z $. If you use $ as a price monetary unit only once in a paragraph, you are going to be fine. But if you have at least 2 dollar signs in the same paragraph, WP Scholar will interprete it as an equation enclosing and try to format it as maths. To prevent that, you need to escape the dollar sign with a backslash, like \$.

#Custom post types

To avoid conflicts and performance penalty with custom post types and special pages like cart/checkout pages of web shop plugins, Markdown is parsed only on regular WordPress posts and pages, comments, posts archives, home page and excerpts.

To force Markdown parsing on any post type that uses the_content hook, put somewhere in the page <!-- force-markdown -->.

#Newbie Documentation

#Markdown syntax

The overall logic of Markdown is to replace HTML markup by special characters (brackets, backticks, stars, etc.), spaces and line breaks. Therefore, spaces and line breaks become parts of the syntax and bad spacing (too many or too few) will result in bad parsing.

The Markdown parser is the library PHP Markdown 1.9.0 that has been extended for our needs and for Github Flavored syntax. Here is the complete list of features as part of the Markdown extended syntax : (bold : standard Markdown, italic : extended Markdown, bold italic : WP Scholar addenda)

  • page elements :
    • footnotes,
    • table of content,
    • abbreviations,
  • block elements :
    • paragraphs and line breaks,
    • **headers* (with ***anchors***, see below),
    • blockquotes,
    • lists and nested lists,
    • code blocks (with syntax highlighting, see below),
    • horizontal rules,
    • equation blocks (see “Maths” below),
    • tables,
    • ordered lists,
    • definition lists
    • id and class attributes
  • span elements :
    • bold,
    • italics,
    • links and auto links from url,
    • images,
    • code span,
    • striked text,
    • exponents,
    • indices

Documentations :

* ~~Striked~~
* 2^nd^
* H~2~O

renders as :

  • Striked
  • 2 nd
  • H2 O

WP Scholar also changes inline images parsing a bit, by automatically linking images to themselves, with a rel="lightbox" attribute. This allows most themes and plugins that use a Javascript lightbox to open images full-screen. So, ![alt text](https://mysite.com/image.jpeg "title text") becomes :

<a href="https://mysite.com/image.jpeg" rel="lightbox" class="lightbox" data-rel="iLightbox" data-title="title text" data-caption="alt text">
  <img alt="alt text" src="https://mysite.com/image.jpeg" title="title text">
</a>

#Footnotes

The footnotes are part of the Markdown Extra syntax, extending Markdown, but WP Scholar gives them a hover card. Input [^1] in the text where you want the footnote marker to appear, like here[1], then later in the text (where it is convenient), define the footnote text like [^1]: The text with exactly one space after : and with only one definition by line. Footnotes definitions are added at the end of the text.

The footnotes numbers don’t have to follow in increasing order in the text, but only have to be unique and be linked to the same number among definitions. The parser will reorder them and sort them in increasing order, as they appear in the text. Footnotes can be called several times, but have to be defined only once.

Hover cards appear when the mouse goes over the footnote link and display the content of the footnote without having to scroll to the footnotes.

#Internal linking and TOC

Your headings need to be properly defined, in decreasing order (for example, don’t start your content with a ### or <h3> title and later input a ## on </h3><h2> title). Notice </h2><h1> or # should be reserved for the page title, so your first section title should always be a </h1><h2> or ##.

WP Scholar will create an unique ID selector if the heading doesn’t have one (even for external HTML files included in posts), and will display a # link left of each heading containing the permalink of the section (current page URL + section anchor), when the mouse hovers the heading (try it on this page’s headings). When clicking the #, the full permalink of the section is copied to the clipboard so you can quickly share the sections on the Internet.

Notice the auto-generated ID use the current content of the heading. If you change it later, the permalink will change too. To set an heading ID manually and prevent them from changing in future post editions, you can use :

## Heading text { #heading-text }

Similarly, if a TOC is present in the page, each heading gets a link right of it, going straight to the TOC, to facilitate intra-page navigation.

#Table of contents

Add a [toc depth=3 title="Contents"] shortcode in the text to make a table of content appear at this place. By default, a TOC shows all levels of heading and doesn’t add a title. The TOC are included in a <details> HTML5 markup which should notify search engines properly about its content.

Optional arguments :

depth
How many levels of headings should go in the TOC list, starting from the first heading in the page.
title
The title to set for the TOC box.

Notice TOCs should work also for external HTML embedded in post pages. A widget is provided to display the TOC in a sidebar, in place or in addition of the post TOC. The options are the same.

#Mixing HTML, Markdown and WorPress shortcodes

Pages can contain a mix of HTML and Markdown syntax, however no Markdown will be parsed inside block-level HTML elements by default. This can be used to deal with corner cases, for example with code blocks (in case the inside of Markdown code blocks is still parsed). If you really need to use HTML divisions and want Markdown to be parsed inside, for example to apply CSS classes and styling, you can change that behavior by adding a markdown=1 property :

<div class="your-class" markdown="1">
  **Some** text with *emphasis*.
</div>

More details…

WP Scholar keeps the content of posts as originally written (Markdown + PHP) in the database. This ensures they can be later edited as Markdown again.

However, many Markdown plugins (Jetpack) and editors (TinyMCE and Gutenberg) support Markdown for typing, but convert to HTML at some point (possibly with their own CSS selectors which will mess-up styling for us) and save posts as HTML in the database. This will make it impossible to edit posts as Markdown again.

WordPress usual shortcodes are rendered after the Markdown parsing is performed, so you can combine shortcodes and Markdown with no fear of clashes. The Markdown parser will treat WordPress shortcodes as standard text, so mind your paragraphs breaks between shortcodes and content (best policy is generaly to avoid empty lines between shortcodes and content to avoid breaking them apart in different paragraphs in the Markdown parsing).


graph TD
  A([Typed post content]) --> B[Markdown parsing]
  B --> C[WordPress shortcodes]
  C --> D[WordPress content filters]
  D --> E[WP Scholar typographic enhancements]
  E --> F([Final post])

How WP Scholar processes your posts

#Typography

Good typography really makes a great difference in the life of people who have to read a lot. Also, properly composed text is just more pleasing. Computer typewriting has been responsible for enforcing bad typographic habits over traditional and professional typography, making things like thin space fall into disgrace simply because they have no place to sit on your keyboard anymore (seriously, do you even know what they are for ?).

Thin space has the width of a coma and used to be recommended before colon (:), semi-colon (;), question and exclamation marks ( !?) in both English and French. Their use has simply disappeared with typewriters and computers, and while the French have replaced them with usual space in all these cases, which helps legibility, the English have simply ditched them at all, which is very disagreeable to read. Punctuation simply has to stand out of words, not to get nested in them.

WP Scholar performs automatically these typographic changes to posts, comments and pages :

  • insert a mandatory unbreakable thin space :
    • before : ; ! ?
    • after ¡ 
    • inside French guillemets « »
    • between numbers and their units (as recommended by the SI Unit style), like 21 kg.
    • between every thousand in numbers if the WordPress locale (language) is set to French,
  • insert a mandatory breakable en space :
    • after : ; ? ! . ,
    • before and after inline code elements
  • convert :
    • quotes :
      • straight single and double quotes '...' and "..." to curly typographic quotes ’…’ and “…” in non-French languages,
      • straight double quotes "..." and double chevron <<...>> into guillemets « … » for French languages,
      • two single quotes ''...'' into proper double quotes ”…”
    • punctuation :
      • 3 dots ... into ellipsis …
      • approximative dashes --- and -- to proper em and en dashes — and –
    • arrows :
      • approximative single and double arrows <-, ->, <—>, <=, =>, <> to ←, →, ↔, ⇐, ⇒, <>
      • approximative tailed arrows >->, <-<, |->, <-| to ↣, ↢, ↦, ↤
    • maths :
      • ~= and \= to ≃ and ≠
      • star multiplication 5*8 to 5×8 
      • plus or minus +/- to ±
      • fractions 1/2, 1/3, 99/100 to ½, ⅓, 99⁄100 (but let dates like 20/09/2019 alone).

#Intermediate documentation

#Mermaid charts

The Mermaid library allows to render graphs as SVG from a couple of Mardown-like commands. The syntactic overhead makes it very efficient to render simple graphs with text properly scaled at display size and DPI, like Gant charts, flow charts, pie diagrams, sequence charts, etc. Simply write a code block with mermaid as the language and type your graphs specifications (more info on the syntax) :

  ```mermaid
  graph TD
    A[Client] --> B[Load Balancer]
    B --> C[Server01]
    B --> D[Server02]
  ```
graph TD
  A[Client] --> B[Load Balancer]
  B --> C[Server01]
  B --> D[Server02]
  ```mermaid
  pie
    title Key elements in Product X
    "Calcium" : 42.96
    "Potassium" : 50.05
    "Magnesium" : 10.01
    "Iron" :  5
  ```
pie
  title Key elements in Product X
  "Calcium" : 42.96
  "Potassium" : 50.05
  "Magnesium" : 10.01
  "Iron" :  5

Mermaid charts can be drawn from Markdown, but also from any <code></code> HTML element with a class="mermaid" like :

<pre class="graph">
  <code class="mermaid">
  pie
    title Key elements in Product X
    "Calcium" : 42.96
    "Potassium" : 50.05
    "Magnesium" : 10.01
    "Iron" :  5
  </code>
</pre>

The <pre></pre> tag is facultative but highly recommended for HTML5 conformity and proper block display.

#Import and include external Markdown and HTML to WordPress posts

WP Scholar lets you import pure Markdown files or rendered HTML files directly to your media library, to include them in posts, pages and custom types. Markdown files are typically simple text files saved with a .md extension.

Upload the file to your media library, like any image, then use the shortcode [include path="path/file.html" load="plotly, mathjax, jupyter"] where path is the complete path of the file within your wp-content/uploads directory (using a year/month/structure if enabled, or just blank if media are loaded directly in uploads).

The load argument is optional and forces the relevant assets to load in order to properly render your include :

jupyter
Loads the default Jupyter stylesheet. The Jupyter stylesheet is the only one that is never auto-loaded, so you could force your own stylesheet or you need to add this argument everytime.
mathjax, plotly, bokeh
Forces the relevant javascript files to load. These should be detected automatically, set it explicitly if they are missed.

The includes are nested in a <> container that gets a generic CSS class include and specific classes plotly, jupyter and mathjax, so you can style them in CSS using these selectors :

.include .jupyter {
  font-size: 1.1em;
}

Markdown syntax is always parsed in external files, then, WordPress shortcodes and typographic enhancements are also applied on the result. So you can write your WordPress blog in a static fashion, by just giving it Markdown posts or exported HTML files.

#Expert Documentation

#Jupyter notebooks, Plotly & Bokeh graphs

Jupyter notebooks are a great way to quickly perform scientific computation, data-mining, text parsing, or even labs in Python, Julia and now C, straight from a web browser. They provide plenty of GUI widgets that let you wire them to your Python functions, to vary parameters, and get the real-time graph straight below the code cells. They also let you write Markdown and $\LaTeX$ which means you can have text, explanations, equations, images, straight along your code and output graphs and table. So you can actually write casual scientific articles straight in notebooks (see an example).

Bokeh and Plotly are 2 libraries to render graphs, compatible with Python, Matlab, and many others. They are of great use to us because they allow interactive graphs, rendered as SVG directly from the values to plot, through a javascript lib. Interactive graphs let users zoom in/out, select points and get a value reading, or even rotate 3D graphs in space. You can put interactive extra labels and annotations on there too, so users can unfold them when they want, but they stay hidden/discrete otherwise.

Notebooks and graphs need to be exported to pure HTML pages. See above to include them from HTML into WordPress pages. We will see here how to export them to HTML.

#Export Jupyter to HTML

jupyter nbconvert --to=html --template=basic notebook.ipynb notebook.html

#Export Plotly to HTML

Note : Don’t embed Plotly.js in the exported files, it is too heavy and redundant if you have several graphs on the same page. WP Scholar will load Plotly.js automatically, wherever it is needed, but only once per page and properly through the generic WordPress script enqueueing, which means it will be handled by caching plugins if you have them.

import plotly.express as px
fig = px.line(x=range(10), y=range(10)) # just a dummy graph
fig.write_html("plotly_sample.html", include_plotlyjs = False)

The important part is the include_plotlyjs = False. Then, using [include path="2021/03/plotly_sample.html"], we get : 

#Export Bokeh to HTML

Same idea, we need to actively tell Bokeh to not embed the Bokeh.js in the export HTML, we take crare of that ourselves.

from bokeh.plotting import figure, show, output_file
p = figure()
p.line(x=range(10), y=range(10)) # just a dummy graph
output_file(filename="bokeh_sample.html", mode="server")
show(p)

The important part being mode="server", which does not actually remove the javascript but rather tell Bokeh to go fetch a local lib that is not there (on localhost). This trick will produce an error in JS console, but Bokeh has no way to just remove any JS and simply produce HTML. So [include path="2021/03/bokeh_sample.html"] gives :

Static HTML file


Note : I personaly find that Bokeh reeks of bad design. The HTML they produce is amateur-level, they don’t support responsive width and the whole look is very much high-school. It is provided here only as an alternative, also because it is slightly lighter than Plotly.


#Maths and chemical equations

The $LaTeX$ support is provided by Mathjax.js 3.1.2 wherever it is detected. The page content is searched for equations, and if some are found, Mathjax.js script is loaded. For performance, comments are not searched, which means if the main content (post or page content) has not triggered Mathjax loading, equations will not be rendered in comments. This is intended to prevent commentors to go pedantic with LaTeX in the comments on pages that didn’t contain equations in the first place.

#Inline mode

Type your equations between $ (with no inside space), like $\LaTeX$ for inline equations. Renders : $\LaTeX$.

For compatibility with other WordPress $\LaTeX$ plugins, the inline mode also supports the shortcode syntax [latex]...[/latex] and the Jetpack syntax $...$ but they are all converted to inline math display. Optional parameters of the Jetpack plugin, like size and colors, are not supported (aka the trailing &s=X and &bg=X before the closing $). Similarly, latex shortcodes using parameters are not supported.

#Display mode

Type your equations between $$ (with no inside space), like $$\LaTeX \label{eq-a}$$ for equations in display mode, and add at least one line break between the previous text and the $$ opening the equation. Renders :

$$
\LaTeX \label{eq-a}
$$

Display mode has equations numbering enabled by default (that will be incremented page-wise) and can be disabled by using \nonumber in the equation. Labels/references can be used, so $\eqref{eq-a}$ renders $\eqref{eq-a}$.

#Display mode in equation block

In case you need to protect line breaks inside equations in display mode, for example with environments, you need to input the equations as an equation block, with one empty line before and after $$ :

$$
\begin{align}
\iint_{-a/2}^{a/2} i^2 \cdot e^{-\frac{i^2}{2 \sigma^2}} \cdot e^{-\frac{j^2}{2 \sigma^2}}\, \mathrm{d}i \, \mathrm{d}j 
  &= \int_{-a/2}^{a/2} e^{-\frac{j^2}{2 \sigma^2}} \, \mathrm{d}j \, \cdot \int_{-a/2}^{a/2} i^2 \cdot e^{-\frac{i^2}{2 \sigma^2}} \, \mathrm{d}i \\\
  &= \sqrt{2 \pi \sigma^2} \, \cdot \, \frac{1}{2}\sqrt{8 \pi \sigma^6} \\\
  &= \frac{\sqrt{16 \pi}}{2} \sigma^4
\end{align}
$$

renders :

$$
\begin{align}
\iint_{-a/2}^{a/2} i^2 \cdot e^{-\frac{i^2}{2 \sigma^2}} \cdot e^{-\frac{j^2}{2 \sigma^2}}\, \mathrm{d}i \, \mathrm{d}j 
  &= \int_{-a/2}^{a/2} e^{-\frac{j^2}{2 \sigma^2}} \, \mathrm{d}j \, \cdot \int_{-a/2}^{a/2} i^2 \cdot e^{-\frac{i^2}{2 \sigma^2}} \, \mathrm{d}i \\\
  &= \sqrt{2 \pi \sigma^2} \, \cdot \, \frac{1}{2}\sqrt{8 \pi \sigma^6} \\\
  &= \frac{\sqrt{16 \pi}}{2} \sigma^4
\end{align}

$$

This particular equation is using align environment and needs line breaks to be honoured at parsing time. To ensure that, you need to enclose it exactly as shown in the code snippet above in an equation block :

  • one empty line before,
  • $$ alone on a line, then a new line,
  • $\LaTeX$ code as usual, possibly with internal line breaks,
  • a newline, then $$ alone on a line,
  • one empty line after.

Failure to comply with these instructions results in garbled line breaks and garbled layout.

#Available plugins

The AMS and Physics packages are loaded at startup, which gives you access, out-of-the-box, to many helpers :

  • equations labelling and referencing through \label, \ref and \eqref tags,
  • equations numbering and aligning, through \begin{env}...\end{env} environments like align, equation, etc. (see the complete list of available environments),
  • usual MathJax and/or $\LaTeX$ packages will be loaded automatically if their use is detected. This includes : action, amscd, bbox, boldsymbol, braket, cancel, color, enclose, extpfeil, html, mhchem (chemical expressions), newcommand, unicode, verb,
  • custom packages can be loaded while typing by adding a \require{package} before the equations (see the complete list of available extensions)

#Warnings

  1. White lines (double line breaks) are not permitted inside a $\LaTeX$ markup,
  2. White lines around equations (before and after) in display mode are mandatory, no matter if you are in maths block or not. Otherwise, equations are not detected.
  3. LaTeX line breaks (\\\ character) are not yet supported in Mathjax 3.1,
  4. Only maths block will ensure the content of an equation will be completely escaped from any Markdown parsing and change. Remember we are stacking a LaTeX → MathML parser on top of a Markdown → HTML parser, all these languages share some common characters that have a different meaning for each of them, so always add a space between LaTeX commands (even though pure LaTeX doesn’t need it), use line breaks wisely and avoid mixing up HTML in your equations.

#Code syntax highlighting

Enclose your code inside 3 backticks (usual Markdown fenced code block) and mention the programming language on the first line, like :

```python
import numpy as np
x = np.linspace(0, 1)
y = np.exp(- x**2 / 2)
```

This will automatically render the code block with syntax highlighting for the current language :

import numpy as np
x = np.linspace(0, 1)
y = np.exp(- x**2 / 2)

To get the syntax highlighting similarly in any <pre></pre> element, defined in HTML instead of Markdown, you simply need to add it a <pre class="language-xxx"></pre> (where xxx is the current language, python in this instance).

If you want to enable line numbering on a specific block of code, you need to add it a class="line-numbers", which can be done directly on the <pre></pre> HTML element or in Markdown by using the custom classes handler :

``` { .language-python .line-numbers }
import numpy as np
x = np.linspace(0, 1)
y = np.exp(- x**2 / 2)
```

which renders :

import numpy as np
x = np.linspace(0, 1)
y = np.exp(- x**2 / 2)

Notice you need to input language-xxx in full with that configuration and leave a blank space between ``` and {.

For better performance, the presence of code blocks to highlight is detected at parsing time, and the Prism.js autoloader is enqueued to the WordPress page only at that condition. Then, the autoloader is executed in the client’s browser and checks the languages currently used on the page, to only load the relevant syntaxes. This ensures minimum bloatware and page loading time.

The language parameter is optional in code blocks and if no language is provided, the parser defaults to a generic code block without styling. To get a styled block but without syntax highlighting, you can declare the language as none.

#Helpers

#Disable Markdown rendering and typography enhancements

To enable the Markdown parsing and avoid formatting conflicts, WP Scholar needs to disable WordPress auto-formatting filters. If, for some reason, this was to clash with page builders or other features, it is possible to disable WP Scholar entirely, on a page-wise basis, by adding the following HTML comment anywhere in the page : 

<!-- no-markdown -->

This will re-enable default WordPress formatting and style. Similarly, to disable the typographic enhancements :

<!-- no-typography -->

#Disable table of contents page-wise

If you opt-in for the table of contents widget and display TOC in sidebars globally, you can chose to disable it selectively on a page-wise basis, using the comment :

<!-- no-sidebar-toc -->

#Force javascript loading

At anytime, anywhere in a post, if for some reason (usually a conflict with encoding or with cache plugins) the javascripts ressources didn’t load, you can force them by adding one of these HTML comments tag in your post :

<!-- mathjax --> 
<!-- bokeh -->
<!-- plotly -->

#Figures and captions

Markdown only allows simple images in the content. A shortcode is provided to embed images, tables or code blocks in HTML5 <figure> elements and add captions without having to deal with the Markdown compatibility :

[figure align="center" id="that-graph"]
![](https://eng.aurelienpierre.com/wp-content/uploads/sites/8/2021/02/hue-linearity.jpg "Title")
[figcaption]
The legendary hue linearity and uniformity of CIE Lab/Luv 1976 compared to IPT from Fairchild, IC~T~P~T~ from ITU-R BT.2100, CIECAM 2016 UCS, and JzAzBz.
[/figcaption]
[/figure]

will render :

The legendary hue linearity and uniformity of CIE Lab/Luv 1976 compared to IPT from Fairchild, ICTPT from ITU-R BT.2100, CIECAM 2016 UCS, and JzAzBz.

Available and optional arguments :

align

As per usual WordPress image alignments, the value align can take 4 arguments that will attribute a CSS class to the figure :

  • none ⇒ CSS class alignnone,
  • left ⇒ CSS class alignleft,
  • center ⇒ CSS class aligncenter,
  • right ⇒ CSS class alignright.
id

A CSS identifier that can be used either to style the figure or to make internal links and anchors, like that graph.

The caption can go before or after the image, although usage tends to put it after for images and before for tables. It is also possible to use the HTML markup directly and to tag elements with markdown="1" as shown above.

#Dev/Power-user documentation

#Caching settings

If your caching plugin gets over-zealous with the javascripts used here, you can tell it to exclude the following files. Here is the suggested configuration for WP Rocket (used here) :

Exclude CSS files from minification (since they are already minified) :

(.*).min.css
cdn(.*)

Exclude JS files from minification (again, already minified) :

cdnjs.cloudflare.com/ajax/libs/(.*)
(.*).min.js

JS deferring works for all files, except for plotly, so exclude it :

plotly.js

JS delaying seems to work, so you can add these files :

prism.min.js
mathjax.js
wp-scholar.min.js
tex-svg.js

This page shows the worst possible case where everything is loaded at once. Since Mathjax and Mermaid are meant to render actual code to SVG, they are anyway quite heavy and there is only so much we can do to make loading time bearable.

#Sequence of processing

graph TD
  subgraph Server
    A(["fa:fa-computer Author article input (Markdown + HTML)"]) --> Op1[Page splitting]

    subgraph WP Scholar
      Op1 --> B1([Pure Markdown])
      Op1 --> B2([Pure HTML])
      B2 --> Test1{{is inline parsing forced ?}}
      Test1 -- yes --> Op2
      Test1 -- no --> E
      B1 --> Op2[Markdown parser]
      Op2 --> E([Intermediate HTML result])
      Op45 --> F([Final parsed HTML article])
      F --> K{{"has raw elements to render client-side ?"}}
    end

    subgraph WordPress
      DB[(Database)] --> A
      E --> Op4[WordPress content filters/shortcodes]
      Op4 --> Op45[Typographic enhancements]
      Page([Template header, body, footer]) --> Concat["+"] 
      F --> Concat
    end

    Concat --> HTML([Final HTML page])
  end 

  HTML --> L["https://"]
  K -- yes --> CDN

  CDN[cdnjs.cloudflare.com] -- link --> Concat
graph TD
  L["https://"] --> G

  subgraph Client
    G([Incoming HTML page]) --> J1(["Raw $\LaTeX$ code"]) & J2([Code blocks]) & J3([Raw charts code]) & J5([Raw JSON graphs]) &  J4([HTML elements])
    J1 --> Op5[Mathjax.js]
    J2 --> Op6[Prism.js]
    J3 --> Op7[Mermaid.js]
    J5 --> Op8[Plotly.js]
    Op5 --> H1([Rendered maths])
    Op6 --> H2([Highlighted code])
    Op7 --> H3([Rendered charts])
    Op8 --> H4([Rendered graphs])
    H1 & H2 & H3 & H4 & J4 --> I([Final rendered page])
  end

  CDN[cdnjs.cloudflare.com] --> S["load/cache"] 
  S -.-> Op5 & Op6 & Op7 & Op8

Flow chart of the post/page content parsing

  1. This is a test footnote.