Skip to content

math_spec.typesetting.markdown

GitHub-flavoured Markdown. GitHub renders math with MathJax, so the math is :class:LatexFormat's and only the document layer differs.

Both delimiters are the verbatim pair — $`…`$ inline and a math fence for a block — because GitHub runs Markdown's escape pass inside a $…$ span, stripping the backslash from every escape TeX needs: \mathrm{gen\_bus} reached MathJax as \mathrm{gen_bus}, a subscript, and \{0, 1\} as a group with no braces. The verbatim pair hands the span over untouched, so the math this prints is the math :mod:~math_spec.typesetting.latex prints, and stays what every other MathJax and KaTeX reads too.

MarkdownFormat #

Bases: LatexFormat

See :class:math_spec.typesetting.format.Format. Math is LaTeX's; prose is not.

dash = '—' class-attribute #

document(blocks, *, standalone) #

No preamble: standalone adds the heading a fragment is pasted under.

Source code in src/math_spec/typesetting/markdown.py 
101
102
103
104
105
@override
def document(self, blocks: list[str], *, standalone: bool) -> str:
    """No preamble: ``standalone`` adds the heading a fragment is pasted under."""
    body = paragraphs(blocks)
    return f'## The math\n\n{body}' if standalone else body

equations(lines, *, numbered) #

One fenced block per equation, with the name outside the math.

A label is the name the file gives the line rather than a symbol, so it sets as the code span prose has and math does not, and aligned has nothing to line up across one-equation blocks. numbered is ignored: aligned cannot carry numbers.

Source code in src/math_spec/typesetting/markdown.py 
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
@override
def equations(self, lines: list[Line], *, numbered: bool) -> str:
    """One fenced block per equation, with the name *outside* the math.

    A label is the name the file gives the line rather than a symbol, so it
    sets as the code span prose has and math does not, and ``aligned`` has
    nothing to line up across one-equation blocks. ``numbered`` is ignored:
    ``aligned`` cannot carry numbers.
    """
    del numbered
    blocks = []
    for line in lines:
        block = f'```math\n{self.equation(line)}\n```'
        if line.label:
            block = f'**{self.mono(line.label)}**\n\n{block}'
        blocks.append(block)
    return '\n\n'.join(blocks)

escape(prose) #

Prose with every special escaped, as the other two notations do, and a backtick span kept as the code span it is.

Source code in src/math_spec/typesetting/markdown.py 
60
61
62
63
@override
def escape(self, prose: str) -> str:
    """Prose with every special escaped, as the other two notations do, and a backtick span kept as the code span it is."""
    return escaped(prose, _escape, self.mono)

glossary(entries) #

Source code in src/math_spec/typesetting/markdown.py 
88
89
90
91
@override
def glossary(self, entries: list[Entry]) -> str:
    rows = '\n'.join(f'| {_cell(self.math(e.symbol))} | {_cell(e.meaning)} |' for e in entries)
    return f'| Symbol | Meaning |\n|---|---|\n{rows}'

math(expression) #

Bare math in prose, in the verbatim inline pair rather than $…$.

Source code in src/math_spec/typesetting/markdown.py 
65
66
67
68
@override
def math(self, expression: str) -> str:
    r"""Bare math in prose, in the verbatim inline pair rather than ``$…$``."""
    return f'$`{expression}`$'

mono(text) #

A backtick span — this one lands in prose, not in math.

Source code in src/math_spec/typesetting/markdown.py 
55
56
57
58
@override
def mono(self, text: str) -> str:
    """A backtick span — this one lands in prose, not in math."""
    return f'`{text}`'

note(text) #

Source code in src/math_spec/typesetting/markdown.py 
97
98
99
@override
def note(self, text: str) -> str:
    return text

section(title, body) #

Source code in src/math_spec/typesetting/markdown.py 
93
94
95
@override
def section(self, title: str, body: str) -> str:
    return f'#### {title}\n\n{body}'