Problems and solutions

This section contains some problems that you might run into when using Remark, and the solutions of those problems.

Code and mathematics

Problem

Consider the following example:

$a + `b$ $c` + d$

`a + $b` `c$ + d`

$a + `b$ $c` + d$

a + $b c$ + d

Ideally, the first paragraph would be interpreted as two subsequent math expressions with backtick-symbols, and the second paragraph as two subsequent code segments with dollar-symbols. While the latter works, the former is interpreted as a single math expression.

Diagnosis

The problem lies deep in Python Markdown, which parses inline-patterns — such as code and mathematics — sequentially. This means that one or the other has to be parsed first — there is no context-sensitivity. We chose to parse the backticks before mathematics, to not change the behaviour of Markdown backticks.

The backticks in the first paragraph creates a <code> tag around the content in the backticks — embedded into a math expression. Since this does not make sense, we replace the <code> tag with its text. While this recovers the use of paired backticks in math expressions, single backticks remain a problem, as demonstrated in the example.

Solution

Ideally, the inline-patterns would be parsed recursively, from outside to inside. Then the outside pattern would get to decide how to treat its content (here as raw text). This is unlikely to be fixed in Python Markdown.

At some point we will replace Python Markdown with a dedicated parser for Remark, which solves this problem as well as many others.

Indentation macro is too eager

Problem

In the following, the content of the list-item is meant to continue after the empty line. However, since the latter is indented with a tab, Remark interprets this as a list-item followed by an invocation of the indentation macro.

* This is in the list-item.

    This is also meant to be in the list-item.

This is in the list-item.

This is also meant to be in the list-item.

Solution

Use spaces instead of tabs for Markdown-related indentation.

* This is in the list-item.

    This is also meant to be in the list-item.

This is in the list-item.

This is also meant to be in the list-item.

Or, indent the first non-empty row preceding the invocation of the indentation macro.

* 
    This is in the list-item.

    This is also meant to be in the list-item.

This is in the list-item.

This is also meant to be in the list-item.

SVG-image does not get loaded

Problem

An SVG-image does not get loaded when a Remark-generated html-file is run from a server, but does get loaded when it is run from the hard-disk.

Solution (probable)

The probable cause is that the server does not have the MIME-type correctly assigned for the .svg files.

For example, for the lighttpd web-server, the configuration file /etc/lighttpd/mime-types.conf should be modified to contain the line

".svg"          =>      "image/svg+xml"

The former string is the file-extension of the SVG-image file format, while the latter is its MIME-type.

Files that are not UTF-8 encoded

If you pass Remark a file that is not a valid UTF-8 encoding, Remark replaces each erroneous symbol with � (U+FFFD REPLACEMENT CHARACTER).

Indentation-macro invocation after a multi-line parameter

Problem

It is wanted to write an indentation macro after invoking a macro with a multi-line parameter. However, Remark interprets the parameter for the indentation macro to be part of the preceding macro-invocation.

Solution

Indentation has a double role. It is used both to denote the invocation of the indentation macro, and to denote the range of a multi-line parameter for a macro. Therefore, if one wants to write an indentation macro-invocation directly after a multi-line parameter, there must be some way to tell Remark where the multi-line parameter ends and the indentation macro-invocation starts.

The immediate solution to this problem is to use explicit invocation instead. However, if the used indentation macro is not known to the writer (e.g. it is generated by some automated process), this solution is not applicable. A general solution is to use the Comment macro without a multi-line parameter to divide the parameters.

Example

[[CppCode]]:
    int square(int x)
    {
        return x * x;
    }

    int cube(int x)
    {
        return x * x * x;
    }

[[Comment]]

    Parameters for indentation macro-invocation here.

int square(int x)
{
    return x * x;
}

int cube(int x)
{
    return x * x * x;
}

Parameters for indentation macro-invocation here.

Injecting html to the head section

Html-code can be injected into the head-section of a html-file by storing text in the html_head tag.