DocC for Math

DocC for Math Equations.
DocC has great support for mulitmedia content. But I thought one feature left was Math Equations. Most math equations in DocC are still displayed with pictures.
It would be great if we have something like

@Equations(alignment: .leading ){
     x = @Fraction{ 
              -b + @Sqrt("3"){ b^2 - 4 ac } 
         } over: { 2 a };

    .ln{y} = .int^{y-1}_{0} 1 / {x+1} dx;

    A = @Matrix(delimiter: .curlyBrace) {
         1, 2, .cdots, 10;
         2, 2, .cdots, 10;
         .vdots, .vdots, .ddots, .vdots;
         10, 10, ..., 10;

for formatting math equation. we could have Directives for some special equation structures and .inft, .alpha which can be implemented as enums of special math symbols, as other than decimal numbers it's not so commonly used in equations and follows the intuition of using enum in swift programming language.

And for codes.

@Code(language: .swift) {
     let x = -b + sqrt(b*b - 4*a*c) / 2

it's unnecessary but would bring a more consistent syntax.

As DocC's Directive are like Declarative Syntax in SwiftUI, can we include a DocC struct in SwiftUI that allows you to display a DocC Document.

Besides, @Rows, @Columns saves a lot for more advanced text formatting. I'm wondering if DocC would have greater use just than write documentation for swift. You know, markdown, LaTeX , are all great, one's simple, easy but incapable of advanced text formatting and the left are much powerful but harder, typst is better.

After written all these lines I have realized that what I'm looking for is kind of a typesetting system conforms to swift programming language' syntax. use @Directive for Content modification() for parameters, {} which allows your to write string without quotation marks., and maybe still allow string interpolation.


Mathematical type-setting is outstandingly complicated. I'd rather we not reinvent that wheel, and instead use something like LaTeX by integrating a plugin like MathJax to render it for us.

This is what the Math StackExchange site does, for example. They have a great quick reference path about it: MathJax basic tutorial and quick reference - Mathematics Meta Stack Exchange


I would second such a request for allowing math markup and would recommend LaTex syntax. For example, github's markup engine allows embedding math within $ signs. You would enter something like this $x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}$ to produce the following


If you want to display LaTeX equations in HTML (and no MathML equations, I personally would be happy with LaTeX only), KaTeX is a good choice, because it is way smaller and faster than MathJax, so one could integrate KaTeX into an HTML export (KaTeX uses the MIT license). (MathJax is better if you use exotic characters within your formulas — KaTeX has problems rendering indices for those —, but the range of characters and formulas supported by KaTeX is quite good and should be equal to the formulas supported by AMSTeX.) MathJax and KaTeX both have command line options for converting the formulas based on node.js (but there are conversion tools like Browserify to help executing node.js based JavaScript code without using node.js, maybe this can be applied).

I do not know how DocC is usually displayed when not using the HTML export (e.g. how it is displayed within Xcode), if the display is based on HTML, the integration of KaTeX could (?) be possible. If not, then MathJax is maybe the better option, using its SVG export using its command line?

edit: Just for clarification, you either integrate KaTeX (or MathJax) in an HTML view (keeping the LaTeX formulas in the HTML code), or you use those libraries to convert the formulas (to whatever the according library supports including HTML+CSS, be careful about vertical lineup when using an export). An alternative to integrate the library directly into an export is to reference the according public server, but then the formulas won‘t be displayed when you are offline and maybe you do not want this for security reasons.

1 Like

There also exists a LaTex math mode viewer written entirely in Swift. It comes with several fonts and doesn't need web access to render equations. GitHub - mgriebling/SwiftMath: SwiftMath provides a full Swift implementation of iosMath for displaying beautifully rendered math equations in iOS and MacOS applications. It typesets formulae written using LaTeX in a UILabel equivalent class.


KaTeX or MathJax also do not need web access.

Great tool. But it needs an Apple platform?


Yes, I was thinking about the XCode DocC viewer.

Quickly resurrecting this thread to give a shout-out to MathML as an alternative to LaTeX that can already be embedded in DocC. The trick is that, since MathML and SVG are both web standards, the following is a perfectly legal SVG file (that can be inserted into your DocC like any other image):

<svg:svg xmlns:svg="" viewBox="0 0 130 50" version="1.1">
    <svg:foreignObject width="130" height="50">
        <math xmlns="">
            <mspace width="5px"/>
            <munderover displaystyle="true">

I recommend saving the above to a .svg file and seeing what it looks like. To support dark mode, just make an exact copy and

  1. Add style="color: white" to the copy's <math> tag.
  2. Add ~dark to the copy's filename.

This MathML+SVG trick is how I typeset math in my documentation; in fact, the SVG above is copied verbatim from a Swift package I'm working on.

This trick is, of course, not ideal. We need to:

  1. Keep two separate files (one for light mode and one for dark) in sync
  2. Wrap the MathML in a bunch of SVG nonsense
  3. Manually size the svg viewBox and the foreignObject

And the image on the documentation webpage will be an <img> of a .svg containing MathML, not an <svg> and certainly not a <math> (which would be ideal, especially for accessibility; alt texts are no replacement for being able to navigate an equation). So I do agree that first-class support for mathematical typesetting would be a welcome addition to DocC. But I believe that MathML would be a much better choice than LaTeX.


having worked on something similar years ago, i agree that MathML+SVG is definitely the way to go, but i think the problem:

is going to be the principal outstanding issue. nobody wants to indent XML to write an equation! but trying to invent a concise math expression DSL seems like a huge undertaking in and of itself.

can’t we just emit the <svg> element directly into the HTML content?

1 Like

Writing MathML without some tool is tedious, whereas writing some LaTeX code is kind of easy, so I would rather like to use LaTeX in my own documentation.

MathML is used a lot in technical communication, whereas in the academic world LaTeX is the standard. The support for MathML by web browsers (or web components in other software) is not really good, so for a good coverage and presentation you need tools like MathJax (maybe to output HTML+CSS already in the conversion process, see above). (For LaTeX embedded in HTML also see the comments above about KaTeX.)


…If LaTeX embedded in HTML + KaTeX is seen a good choice from some technical standpoint, it might be a good idea to support MathML by converting MathML to LaTeX for the output, either by using MathJax (update: no: see the correction below) or some other conversion tool (I have a Swift package that can convert between some formula formats, I would like to talk with my partners about open-sourcing it anyway).

Correction: MathJax never had a LaTeX output processor. MathJax used to have a MathML output processor (it uses MathML as its internal format) but for some reason dropped it in version 3. See the MathJax documentation.

As far as I know, not with “vanilla” DocC. To add an <svg> to the DocC-generated website, we’d have to process the website after DocC generates it (with a custom script, or a compiler plugin, etc). But, if we’re going to do that, then we might as well emit a <math> instead of an <svg>.

Embed math using <math> Embed math using <svg>, <embed>, <object>, etc
To support dark mode, nothing needs to be done because <math> uses the current font color. To support dark mode, we’d also have to change the generated webpage’s stylesheet to add a media query (this can’t be done with inline styles).
Users viewing the documentation webpage with a screen reader can navigate the equation. Possibly insufficient accessibility.

Though, instead of doing either of these, I’ll personally stick to vanilla DocC and just embed math as an <img> of a .svg (using the MathML-in-SVG trick in my original comment, though people who prefer LaTeX over MathML can instead compile their LaTeX to .svg).

That said, if DocC were to gain first-class support for mathematical typesetting in the future, then embedding math into documentation pages via <math> (the ideal approach) would become tractable. I’ve made a separate post about this here.

The support for MathML by web browsers (...) is not really good

Now that Chromium has (finally) adopted MathML Core, is this still true?

That Chromium only recently (OK, six months ago) has got its MathML support back is news to me. But it still does not look good see an example. And there is also WebKit (and some people are still using Firefox).

And I really think it would be a mistake not to support LaTeX. As I have written before, you do not want to add MathML without some kind of tooling (which many people might not have). LaTeX formulas on the other hand are easily added without any tool, their syntax being short and quite easy, and usually someone who is “interested” im math (and so would likely add math formulas to a documentation) knows the LaTeX syntax very well, but is not likely to want to learn and write MathML.

1 Like