Writing Like a Pro with Markdown, Mermaid, and LaTeX

Capstone Design

Imron Rosyadi

Writing Like a Pro with GitHub Flavored Markdown, Mermaid, and LaTeX

This deck teaches students three related skills they can use directly in GitHub and many other tools:

1. GitHub Flavored Markdown (GFM) for documentation, READMEs, and reports.
2. Mermaid diagrams for architecture, flowcharts, and sequence diagrams directly in Markdown.
3. LaTeX math in Markdown for equations and derivations.

Emphasize that these are lightweight but powerful tools that integrate directly with GitHub, issues, PR descriptions, and documentation sites.

Learning Objectives

By the end of this session, you will be able to:

1. Write clear documents using GitHub Flavored Markdown (GFM).
2. Create structured diagrams with Mermaid directly in Markdown.
3. Write mathematical equations using LaTeX syntax inside Markdown.
4. Combine text, diagrams, and equations into rich technical documentation for ECE projects.

Highlight that these skills apply across courses: lab reports, design docs, README files, documentation for firmware, HDL, simulations, etc.

Big Picture: Why These Tools Matter

• Most engineering collaboration happens in:
  • GitHub READMEs and wikis.
  • Issues and pull requests.
  • Documentation repos (e.g., MkDocs, Quarto, Docusaurus).
• GFM + Mermaid + LaTeX let you:
  • Explain algorithms and protocols.
  • Show system architectures.
  • Derive and present equations.
• All using plain text files in your repo.

Explain that these formats are:

• Version-controllable.
• Code-reviewable.
• Rendered nicely on GitHub and in many documentation tools.

No need for heavy Word/PowerPoint docs for many technical artifacts.

Part 1: GitHub Flavored Markdown (GFM) – Overview

GitHub Flavored Markdown extends basic Markdown with extra features:

• Headings, lists, emphasis, code blocks.
• Tables, task lists, and fenced code blocks with syntax highlighting.
• Inline HTML (in some cases).

You can use GFM in:

• README.md, CONTRIBUTING.md, LABx.md.
• Issues and PR descriptions.
• Wiki pages.

Note

Markdown is plain text → easy to diff, review, and version using Git.

Mention that GFM is the “dialect” GitHub uses.

Students may have seen Markdown in other tools (e.g., Slack, Discord, Jupyter) – many concepts carry over.

GFM Basics: Headings and Paragraphs

Use # for headings:

## Section Heading

### Subsection Heading

Rendered result:

Section Heading

Subsection Heading

Paragraphs:

• Separate paragraphs with a blank line.
• No special marker needed.

This is a paragraph describing the project.

This is another paragraph with more detail.

Encourage descriptive headings: “Signal Acquisition Pipeline” instead of “Section 1.”

Headings make documents scannable and auto-generate tables of contents in some tools.

GFM Basics: Emphasis and Line Breaks

Use * or _ for emphasis:

This word is *italic*.

This is **bold**.

You can combine ***bold and italic***.

Rendered:

This word is italic. This is bold. You can combine bold and italic.

Line breaks:

• One line in Markdown usually wraps automatically.
• To force a line break without a new paragraph, end the line with two spaces.

Line one with a forced break.
Line two appears directly below.

Explain that for GitHub specifically, two spaces at end of line → <br> break.

Good for addresses, list items with multiple lines, or poetry; but don’t overuse.

GFM Lists: Bulleted and Numbered

Bulleted list:

- First item
- Second item
  - Nested item
- Third item

Rendered:

• First item
• Second item
  • Nested item
• Third item

Numbered list:

1. Step one
2. Step two
3. Step three

1. Step one
2. Step two
3. Step three

Mention that numbering can be auto-generated (you can write 1. for every item and GitHub will number them).

Nested lists are useful for substeps or comments.

GFM Code: Inline and Blocks

Use backticks for inline code:

Use the `adc_read()` function to sample the signal.

Use triple backticks for code blocks (optionally with language):

```c
uint16_t sample = adc_read();
process_sample(sample);
```

Rendered:

uint16_t sample = adc_read();
process_sample(sample);

Tip

Always specify the language (e.g., c, python, verilog) for syntax highlighting.

Highlight that inline code is great for function names, file paths, CLI commands, etc.

Code blocks are crucial in documentation of APIs, setup instructions, and lab guides.

GFM Tables

Tables in GFM are ASCII-based:

| Signal | Type   | Description             |
|--------|--------|-------------------------|
| VIN    | Analog | Input voltage (0–3.3 V) |
| VOUT   | Analog | Filtered output         |
| CLK    | Digital| System clock input      |

Rendered:

Signal	Type	Description
VIN	Analog	Input voltage (0–3.3 V)
VOUT	Analog	Filtered output
CLK	Digital	System clock input

You can align columns using colons:

| Name  | Value |
|:------|------:|
| R1    | 10 kΩ |
| C1    | 0.1 µF|

Tables are extremely useful for pinouts, parameter lists, test cases, etc.

Warn that tables are somewhat tedious by hand; tools exist to help generate them, but practice helps.

GFM Task Lists and Links

Task lists (often used in issues and PRs):

- [ ] Implement ADC driver
- [x] Write unit tests
- [ ] Update documentation

Rendered as checkboxes on GitHub.

• Implement ADC driver
• Write unit tests
• Update documentation

Links:

[GitHub](https://github.com/)

[Lab 3 Instructions](./LAB3.md)

Rendered:

GitHub
Lab 3 Instructions

Note

Task lists are great for TODOs in issues or project boards.

Point out that relative links like ./LAB3.md work within the repo, and make navigable documentation.

GFM Image Embeds

You can embed images directly:

![Block diagram of the system](./images/unsoed_logo.png)

Rendered:

Example: logo Unsoed

(Your actual image would appear here.)

Tips:

• Keep images in a folder like images/ or docs/img/.
• Use meaningful alt text: describes the image content.

In ECE projects, images may include oscilloscope screenshots, PCB layouts, or block diagrams exported from tools.

Also mention that some diagram types can be done as text via Mermaid, which we’ll cover next.

GFM Example: Mini README

# FFT-Based Spectrum Analyzer

This project implements a real-time spectrum analyzer on an embedded board.

## Features

- 12-bit ADC sampling at 20 kHz
- 1024-point FFT using CMSIS-DSP
- UART output for spectrum data

## Usage

1. Flash the firmware to the board.
2. Open a serial terminal at `115200` baud.
3. Observe frequency peaks as you vary the input signal.

## TODO

- [ ] Add windowing options
- [x] Implement basic FFT
- [ ] Document serial protocol

Walk through this example: headings, lists, code, and task list all in one.

Encourage students to create such a README for each of their labs or projects.

Part 2: Mermaid Diagrams – Overview

Mermaid lets you describe diagrams as text blocks in Markdown.

GitHub supports Mermaid in:

• Markdown files (.md).
• GitHub Wiki pages.
• Some other contexts.

Common diagram types:

• Flowcharts.
• Sequence diagrams.
• Class / entity-relationship diagrams.
• State diagrams, Gantt charts, etc.

Important

Mermaid diagrams live in your repo as code, so they can be versioned, reviewed, and edited like any other file.

Explain that Mermaid reduces friction: no need for external drawing tools and exported images for many diagrams.

This is very useful for system architecture, dataflow, and protocol sequence diagrams.

Mermaid Basics: Flowchart Syntax

Basic pattern in GitHub Markdown:

```mermaid
flowchart LR
  A[Start] --> B[Process]
  B --> C{Decision?}
  C -->|Yes| D[Branch 1]
  C -->|No|  E[Branch 2]
```

Rendered (conceptually):

Key elements:

• flowchart LR → left-to-right flowchart.
• Nodes: A[...], B(...), C{...} etc.
• Edges: A --> B, optionally with labels: C -->|Yes| D.

Explain briefly node shapes:

• [...] = rectangular.
• ( ) = rounded.
• { } = decision / diamond.

Mermaid renders these automatically.

Mermaid Flowchart: ECE Example

ADC sampling + DSP + UART pipeline:

```mermaid
flowchart LR
  IN[Analog Input] --> ADC[ADC Sampling]
  ADC --> DSP[Digital Signal Processing]
  DSP --> UART[UART Formatter]
  UART --> PC[PC Visualization]
```

Rendered:

Use this in:

• README to show system overview.
• Design document to explain data flow.

Point out that updating the pipeline (adding, say, a filter stage) is as simple as editing text.

No need to open drawing software.

Part 3: LaTeX Equations in Markdown – Overview

For math, many Markdown renderers (including Quarto and some GitHub contexts) support LaTeX syntax:

• Inline math: $ ... $
• Display (block) math: $$ ... $$

Examples work in:

• Quarto documents and slides.
• Many static site generators.
• Some GitHub tools (GitHub itself has limited direct LaTeX support, but GitHub Pages with MathJax, Quarto, etc., can render it).

Warning

GitHub’s native Markdown does not render LaTeX as math in all views by default. However, Quarto, Jupyter, and many documentation setups built on GitHub do.

Clarify this nuance: in this course, they’ll often view LaTeX-rendered math through Quarto, Jupyter, or other tools that support it.

The syntax is still standard LaTeX math mode.

Inline vs Display Math

Inline math:

The sampling frequency is $f_s = 20\,\text{kHz}$ in this design.

Rendered:

The sampling frequency is \(f_s = 20\,\text{kHz}\) in this design.

Display math:

The discrete-time Fourier transform (DTFT) is given by

$$
X(e^{j\omega}) = \sum_{n=-\infty}^{\infty} x[n] e^{-j \omega n}
$$

Rendered:

The discrete-time Fourier transform (DTFT) is given by

\[ X(e^{j\omega}) = \sum_{n=-\infty}^{\infty} x[n] e^{-j \omega n} \]

Explain that inline math flows with text; display math is centered and on its own line, making it easier to read for larger expressions.

Common LaTeX Symbols and Expressions

Some useful patterns:

- Greek letters: $\alpha$, $\beta$, $\omega$, $\Omega$, $\phi$
- Subscripts: $x[n]$, $y_k$, $V_{\text{in}}$
- Superscripts: $e^{j\omega}$, $x^2$
- Fractions: $\frac{1}{2}$, $\frac{V_{\text{out}}}{V_{\text{in}}}$
- Square roots: $\sqrt{2}$, $\sqrt{1 - \alpha^2}$
- Sums and integrals: $\sum_{n=0}^{N-1} x[n]$, $\int_0^T v(t)\,dt$

Rendered examples:

• Greek letters: \(\alpha\), \(\beta\), \(\omega\), \(\Omega\), \(\phi\)
• Subscripts: \(x[n]\), \(y_k\), \(V_{\text{in}}\)
• Superscripts: \(e^{j\omega}\), \(x^2\)
• Fractions: \(\frac{1}{2}\), \(\frac{V_{\text{out}}}{V_{\text{in}}}\)
• Square roots: \(\sqrt{2}\), \(\sqrt{1 - \alpha^2}\)
• Sums and integrals: \(\sum_{n=0}^{N-1} x[n]\), \(\int_0^T v(t)\,dt\)

Encourage students to keep a cheat sheet of commonly used LaTeX commands; they will quickly memorize the ones they use frequently.

ECE Example: Discrete-Time Filter

A first-order IIR low-pass filter can be written as

$$
y[n] = (1 - \alpha)\,x[n] + \alpha\,y[n-1],
$$

where $\alpha \in [0,1]$ controls the smoothing.

Rendered:

A first-order IIR low-pass filter can be written as

\[ y[n] = (1 - \alpha)\,x[n] + \alpha\,y[n-1], \]

where \(\alpha \in [0,1]\) controls the smoothing.

Use this to show how to properly space and align terms.

Note the use of \, for a small space and \in for “is in.”

Systems Example: Transfer Function

The transfer function of a simple RC low-pass filter is

$$
H(j\omega) = \frac{1}{1 + j \omega R C}.
$$

The magnitude response is

$$
|H(j\omega)| = \frac{1}{\sqrt{1 + (\omega R C)^2}}.
$$

Rendered:

The transfer function of a simple RC low-pass filter is

\[ H(j\omega) = \frac{1}{1 + j \omega R C}. \]

The magnitude response is

\[ |H(j\omega)| = \frac{1}{\sqrt{1 + (\omega R C)^2}}. \]

Highlight how LaTeX keeps formulas readable and avoids ambiguity that plain text may introduce.

These examples are directly relevant to signals/systems and circuits courses.

Matrices and Vectors

The state vector is

$$
\mathbf{x} =
\begin{bmatrix}
x_1 \\
x_2 \\
x_3
\end{bmatrix}.
$$

The state-space model is

$$
\dot{\mathbf{x}} = A \mathbf{x} + B \mathbf{u}, \quad
\mathbf{y} = C \mathbf{x} + D \mathbf{u}.
$$

Rendered:

The state vector is

\[ \mathbf{x} = \begin{bmatrix} x_1 \\ x_2 \\ x_3 \end{bmatrix}. \]

The state-space model is

\[ \dot{\mathbf{x}} = A \mathbf{x} + B \mathbf{u}, \quad \mathbf{y} = C \mathbf{x} + D \mathbf{u}. \]

This shows how to handle vectors, matrices, and multiple equations with alignment (using \quad for spacing).

Important in control systems and linear algebra-heavy ECE topics.

Combining GFM, Mermaid, and LaTeX

You can mix all three in one Markdown document or Quarto doc:

# Digital Filter Module

We implement a FIR filter with impulse response

$$
h[n] = \begin{cases}
\frac{1}{M}, & 0 \le n < M \\
0,           & \text{otherwise}
\end{cases}
$$

## Data Flow

```mermaid
flowchart LR
  X["Input x[n]"] --> FIR["FIR Filter h[n]"]
  FIR --> Y["Output y[n]"]
```

## Test Procedure

1. Generate a sine wave input using `test_signal.py`.
2. Capture output samples and compute the FFT.
3. Verify that the passband gain is approximately $1$ and stopband is low.

This slide demonstrates “rich documentation”: explanation, math, diagram, and steps all together.

Encourage students to structure design docs in a similar way.

Example: Embedded System Overview Document

# Temperature Monitoring System

## System Overview

```mermaid
flowchart LR
  Sensor[Temp Sensor] --> MCU[Microcontroller]
  MCU --> Display[7-Segment Display]
  MCU --> Logger[UART Logger]
```

## Sensor Model

The sensor output voltage is

$$
V_{\text{out}} = S \cdot T + V_{\text{offset}},
$$

where $S$ is sensitivity (V/°C), and $T$ is temperature in °C.

## TODO

- [ ] Calibrate sensor at 0°C and 100°C
- [ ] Implement UART logging protocol
- [x] Basic display driver

• Uses GFM for structure, lists, and TODOs.
• Uses Mermaid for block diagram.
• Uses LaTeX for sensor equation.
• Entire doc lives in docs/temperature-system.md in the repo.

Point out how much information and structure you can capture in one small text file.

Students can attach such docs to their PRs when adding new subsystems.

Practice Guide: What You Should Try Next

To solidify these skills, create a new Markdown file in a repo:

1. GFM Practice
   • Write a mini-README with headings, lists, code blocks, and a table.
2. Mermaid Practice
   • Add a flowchart of a system (e.g., sensor → MCU → actuator).
   • Add a small sequence diagram for a communication protocol.
3. LaTeX Practice
   • Include at least two inline equations and two display equations.
   • One should be an ECE-relevant formula (e.g., filter equation, Ohm’s law, transfer function).

Tip

Start small. You don’t need perfect diagrams or equations at first. Iterate as you would with code.

Encourage them to push this practice file to GitHub and view it in the browser to see how it renders.

If using Quarto or Jupyter, render locally to verify LaTeX equations and Mermaid.

Summary / Key Points

• GitHub Flavored Markdown (GFM):
  • Use headings, lists, code blocks, tables, task lists, links, and images.
  • Ideal for READMEs, lab guides, and design docs.
• Mermaid Diagrams:
  • Write diagrams as text (flowcharts, sequence diagrams, class diagrams).
  • Perfect for showing data flow, protocols, and architecture.
• LaTeX in Markdown:
  • Use $...$ for inline and $$...$$ for display math.
  • Present equations, derivations, and models clearly.
• Combining all three gives you powerful, maintainable, version-controlled documentation for ECE projects.

Close by emphasizing that good documentation is a core engineering skill, not an optional add-on.

These tools make documentation efficient and closely integrated with code, improving team communication and project quality.