Authoring Professional Documents in Markdown

Graphical editors like Microsoft Word can be very convenient, but they become very unpleasant to use when you need to write large numbers of mathematical formulas. Most professional mathematicians and computer scientists use a typesetting language like Markdown or LaTeX.

  • Historically, LaTeX has been used more widely in mathematics
  • Recent Federal laws require the use of accessible documents in teaching at state universities
  • LaTeX does not produce accessible output

Markdown has several benefits

  • It is easier to write and read than LaTeX
  • It can easily be compiled to accessible HTML using existing compliers like Pandoc

For example, in Markdown you can create a nicely formatted document by putting the following in a file called Sample.md

# Welcome to Math 161

## Class Information 
- **Instructor:** Stephen Flood
- **Office:** DMF 443
- **Textbook:** select one of the following
    - [OpenStax Calculus Volume 1](https://openstax.org/books/calculus-volume-1)
    - [Stewart Calculus](https://www.amazon.com/Calculus-Early-Transcendentals-James-Stewart/dp/1337613924)

If you open this in a markdown enabled viewer, you will see a nicely formatted document. The two blue links will be clickable links, that will take you to the addresses included in the source.

a compiled markdown document

If you use a program like Pandoc, you will be able to compile your document into a nicely formatted and accessible html file that is easily shared.

Previewing Markdown Online

WARNING:

  • Online Preview Websites do NOT save your work
  • Author your document on your computer to avoid losing your work
  • Online sites may also save your data and sell/train AI on it.

Downloading a Markdown Editor

VS Code is a powerful text editor for computer programming.
As an added bonus, it has a built in Markdown Previewer.

  1. Download and install VS Code
  2. Open VS Code
  3. create and save a markdown file.
  4. Open the Previewer one of two ways
    • Type Ctr-K, release the keys, then type V
    • At the top of the window, mouse over the images to find the button that says Open Previewer to the Side

Basic Markdown Syntax

Here are some markdown basics:

  • # begins a section heading
  • ## begins a sub-section heading
  • emphasize text between a pair of *, usually by putting it in italics
  • bold text between a pair of **
  • bold and italics text between a pair of *** 
# Section
## Subsection
*italics*
**bold**
***bold and italics***

Paragraph Structure

Key Concept:

Include a blank line to start a new paragraph.

This is a sentence. 
This sentence is in the same paragraph. 

This sentence will start a new paragraph.
This will be in the second paragraph.

New lines will not (usually) start a new paragraph. You can use this to help organize your thoughts.

Unexpected output?

Small changes in your Markdown code can cause big, unexpected changes in the output. Here are quick solutions to a few common problems.

  • Unexpected line breaks? Two or more spaces at the end of a line will cause a line break, but not start a new paragraph. If you are getting newlines where you don't want them, check the end of the line for extra spaces.

  • Unexpected blocks of unformatted text? Do not use indentation except for Markdown formatting. Indenting text by four extra spaces or one extra tab will make Markdown interpret your text as a code block (see below).

Making Lists

You can easily make itemized lists (not numbered as follows). 

Here is a list of several items

- Item 1
- Item 2
- Item 3

IMPORTANT:

  • There must be one blank line before the first list item.
  • If the blank line is missing, some viewers will typeset the list correctly, and others will treat it as a paragraph and you will see something like the following.
    Here is a list of several items - Item 1 - Item 2 - Item 3.
    If that happens, keep add a blank before the first list item.
  • When you have multiple, nested list, you may need to have blank lines before and after every list item.

You can also make a numbered list as follows 

Here is a list of several items

1. First item
2. Another item
3. Still more items

You can also make nested lists by indenting the sub-list

There are many ways to write documents

- Microsoft word is one 
    - What you see is what you get
    - But you need to click a lot of buttons
- LaTeX is another
    - It creates beautiful PDF documents
    - But these are not always accessible
- Markdown is a third
    - It is very easy to read and write
    - But it is less obvious how to share it

Using Math in Markdown

Although LaTeX is not part of the Markdown language, most Markdown viewers can display mathematical formulas using a tool/library called MathJax.

Suppose I want to type in a mathematical formula such as the following \[\int\dfrac{1}{x} dx = \ln(x) + C\]

Just like in normal LaTeX, you just enclose your text with a pair of $ or $$ signs.

For an inline formula, use single dollar signs.

$ \int \frac{1}{x} dx = \ln(x) + C $

For a display mode formula, use double dollar signs.

$$ \int \frac{1}{x} dx = \ln(x) + C $$

For information on typing mathematics in LaTeX, click here

Writing Code in Markdown

You can also insert code by putting it between pairs of back-ticks `. For example, you can reference the random library and the import random command by by typing

Import the `random` library by typing `import random`

You can also use triple back-ticks ``` to insert blocks of code. Optionally, you can include the type of code (python, latex, markdown, etc), and the markdown viewer will often try to highlight the code accordingly. 

``` python
import random
print(random.randint(1,5))
```

You can include links with the syntax 

[Link Description](https://link_url.com)

You can easily include images posted online.

![Alternate text](https://link_url.com/my_image.png)

You can also include images that are on your personal computer, by including the file address. But it is more complicated to share this document, since you need to figure out how to send the images as well as the Markdown file.

Creating Accessible, Sharable Documents

Markdown files are plain text, and most people do not have a Markdown viewer installed on their computer. Sharing documents by email that reference local images is even more complex. To share a your final document, it is best to convert it into an accessible format like HTML using a tool called Pandoc.

Pandoc has many settings and options. I recommend specific ones below, and you can just copy/paste them without worrying too much.
You can also experiment with different options yourself using the Pandoc Document Previewer

Accessible Web Documents

First, download and install the program Pandoc from https://pandoc.org/installing.html

We will create a shareable HTML file from the file my_file.md.
Pandoc requires that we provide a name for the file you are producing. We can give it a new name output_file.html, but it is more common to just change the extension and name it my_file.html. Then run the command 

pandoc my_file.md -o my_file.html --standalone --embed-resources \
       --mathjax=https://cdn.jsdelivr.net/npm/mathjax@4/tex-mml-chtml.js

This will embed images inside the output html file, and will typeset mathematics formulas using the very accessible format used by mathjax.

Actually, running that command will insert the alt-text into the document, because Pandoc assumes the alt-text is the caption for a figure, when the image shows up in its own paragraph. But under current accessibility guidelines, alt-text should be more than a figure caption. There are lots of ways to fix this in the Pandoc documentation, but the simplest is to use the following command, which just turns off the implicit_figure behavior from the markdown format.

pandoc -f markdown-implicit_figures my_file.md -o my_file.html \
       --standalone --embed-resources \
       --mathjax=https://cdn.jsdelivr.net/npm/mathjax@4/tex-mml-chtml.js

If you are using another more advanced Markdown applications, such as Mkdocs, you might need to wrap your mathematical text in different delimiters like \( ... \) or \\( ... \\) for inline math, or \[ ... \] and \\[ ... \\] for display math. You can use the same source with Pandoc by adding +tex_math_single_backslash or +tex_math_double_backslash 

pandoc -f markdown-implicit_figures+tex_math_double_backslash \
       my_file.md -o my_file.html --standalone --embed-resources \
       --mathjax=https://cdn.jsdelivr.net/npm/mathjax@4/tex-mml-chtml.js

Creating an Elegant Printed Document

You can also use Pandoc to create Word or PDF versions of your document. The easiest way to specify the output format is with your output file extension.
You can create a word docx document using 

pandoc my_file.md -o my_file.docx

You can have Pandoc number sections by adding the --number-sections flag

pandoc my_file.md -o my_file.docx --number-sections

Pandoc also has a number of other flags, such as --toc which inserts a table of contents at the beginning, and -M title="My Title" and -M author="My Name" which add a title and name respectively.

pandoc my_file.md -o my_file.docx --number-sections -M title="My Title" -M name="My Name"

If you have a LaTeX compiler installed, you can compile directly to pdf

pandoc my_file.md -o my_file.pdf --pdf-engine=pdflatex

Or you can create a tex file that you can edit before compiling. But this file will be very hard to read. If you want to maintain a LaTeX source file, you should write one yourself.

pandoc my_file.md -o my_file.tex

Also, if your source uses a non-standard option like using \\(...\\) as the LaTeX delimiters, you need to update the command as with html

pandoc -f markdown+tex_math_double_backslash my_file.md -o my_file.docx --number-sections
pandoc -f markdown+tex_math_double_backslash my_file.md -o my_file.pdf --pdf-engine=pdflatex --number-sections
pandoc -f markdown+tex_math_double_backslash my_file.md -o my_file.tex --number-sections

Advanced Document Features

LaTeX has a clear, robust framework for

  • Automatic numbering of sections
  • Creating and using internal references
  • Managing citations,
  • Creating internal document links
  • Tables
  • Figures
  • and much, much more

Unfortunately, the pure Markdown syntax does not define any of these features.

Pandoc does provide some of these features, as described at
https://pandoc.org/MANUAL.html#pandocs-markdown

There are also other extensions of Markdown that add these features in different ways. Talk to me if you have a specific need.

Making a Website with MkDocs

MkDocs is a python-based site generator.

  • Creates a simple static website from a directory of Markdown files.

  • Originally designed for building project documentation

  • Helpful for taking and organizing notes, and was used to write this website.

A little bit of custom configuration is required to use mathematics in MkDocs.

First, you must add the following to your mkdocs.yaml file:

extra_javascript:
  - https://cdn.jsdelivr.net/npm/mathjax@4/tex-mml-chtml.js

Second, you must convert your inline math delimiters from $...$ to \\(...\\), and your display math delimiters from $$...$$ to \\[...\\].

This is not difficult to do if you are starting from a blank document. If you already have a lot of mathematics that you want to convert, talk to me and I can help.