Writing Reports in Markdown

ECE 3410

Markdown Basics

Markdown is a relatively recent syntax for writing technical documentation, and is intended to simplify and streamline the writing process. It produces high-quality text, equations, and images with minimal effort from the user. Markdown is a text-based syntax, so it can be edited using any text editor. The ECE external drive image contains a few useful tools for processing Markdown:

Essential Syntax

Markdown syntax is very simple, and is documented on many sites like this one. Here are a couple of the main things:

As another example, we use a table to provide a figure caption. Here, the figure is placed in the table’s header row:

| ![](markdown_mark.png)          |
|:-------------------------------:|
| Here is a caption in the table. |
Here is a caption in the table.

Equations in Markdown

Most Markdown tools recognize equations written in the LaTeX format. A LaTeX equation is surrounded by dollar signs ($), and uses a text syntax to represent the parts of an equation. For example:

$c=\sqrt{a^2+b^2}$

This equation renders as \(c=\sqrt{a^2+b^2}\). Here is a quick table of important LaTeX equation features, with usage examples.

Feature Syntax Example Rendered Example
subscript underscore '_' $i_D$ \(i_D\)
superscript caret '^' $x^2$ \(x^2\)
square root \sqrt{} $\sqrt{abcd}$ \(\sqrt{abcd}\)
fraction \frac{}{} $\frac{N}{D}$ \(\frac{N}{D}\)
scaled parentheses \left(\right) $\left(\frac{N}{D}\right)$ \(\left(\frac{N}{D}\right)\)
exponential e^{} or \exp() $e^{2x-1}$ \(e^{2x-1}\)
summation \sum_{}^{} $\sum_{k=1}^{N}x_k$ \(\sum_{k=1}^{N}x_k\)
logarithm \ln() $\ln(x)$ \(\ln(x)\)
text font \text{} $\text{SNR}=2\text{dB}$ \(\text{SNR}=2\text{dB}\)

Next is a table showing some more sophisticated examples that are relevant to ECE 3410.

Example Rendered Example
$H(s) = \frac{s}{1+sRC}$ \(H(s) = \frac{s}{1+sRC}\)
$H(j\omega) = \frac{1}{1+j\omega RC}$ \(H(j\omega) = \frac{1}{1+j\omega RC}\)
$A_{v0} = -\frac{R_2}{R_1}$ \(A_{v0} = -\frac{R_2}{R_1}\)
$A(\text{dB}) = 20\log_{10}(A_{v0})$ \(A(\text{dB}) = 20\log_{10}(A_{v0})\)
$i_D = I_S \exp \left( \frac{v_D}{nU_T} \right)$ \(i_D = I_S \exp \left( \frac{v_D}{nU_T} \right)\)
$v_D = nU_T \ln \left( \frac{i_D}{I_S} \right)$ \(v_D = nU_T \ln \left( \frac{i_D}{I_S} \right)\)
$v(t) = A \sin(2\pi f t)$ \(v(t) = A \sin(2\pi f t)\)
$i_D^\star = \frac{1}{2} \mu_n C_{\text{ox}} \frac{W}{L} \left(v_{GS} - V_{\text{Th}} \right)^2$ \(i_D^\star = \frac{1}{2}\mu_n C_{\text{ox}}\frac{W}{L}\left(v_{GS}-V_{\text{Th}}\right)^2\)
$i_D=i_D^\star\left(1+\lambda v_{DS}\right)$ \(i_D=i_D^\star\left(1+\lambda v_{DS}\right)\)

Converting Files with pandoc

A version of pandoc is installed on the external drive. To use it, open a terminal and navigate to the directory where your markdown file resides. Then run the command

pandoc filename.md -V geometry:margin=1in -o filename.pdf

This is the most basic way to make a PDF file from a Markdown document. Pandoc uses LaTeX to generate the PDF file, and result looks different from what may be produced by Typora or another editor.

To produce an html file, use these options:

pandoc filename.md --katex -s -o filename.html

To add a table of contents, add the --toc option to either of the commands shown above.