typeCAD Documentation Generator Usage Guide

The typeCAD Documentation Generator is a tool to convert markdown files into KiCAD documentation with support for layer exports and renders.

Installation

npm install -g @typecad/typecad-docgen

KiCAD v8 or v9 is also required.
node/npm.js

Basic Usage

typecad-docgen input.md pcb_file.kicad_pcb

This will generate an HTML file with the same name as your input markdown file (e.g., input.html).

All normal markdown is supported
pagination is done automatically by putting everything between # (h1) in a page, centered both horizontally and vertically
Layer export and renders are done with minor markdown syntax additions (see below)

Frontmatter Configuration

You can customize the documentation output by adding frontmatter to your markdown file:

---
title: My PCB Project
company: Acme Electronics
board_name: Main Controller
variant: v1.0
revision: A
date: 2024-03-30
highlight: github-light
stylesheet: https://cdn.jsdelivr.net/npm/github-markdown-css@5.5.0/github-markdown.min.css
kicad_theme: default
dark_mode_default: true
---

Frontmatter Options

Frontmatter options change themes, stylesheets, and provide information for the title block.

Option	Description	Default
`title`	Document title	Empty
`company`	Company name	Empty
`board_name`	PCB board name	Empty
`variant`	Board variant	Empty
`revision`	Revision number	Empty
`date`	Document date	Current date
`highlight`	Code highlighting theme	github-light
`stylesheet`	Custom CSS stylesheet URL	Custom CSS
`kicad_theme`	KiCad color theme	KiCAD Default
`dark_mode_default`	Dark mode	false

Layer Stackup Diagram

To include a PCB layer stackup visualization:

![{Stackup}](images/stackup.png =800)

The information is extracted from the PCB file and is set in the PCB Editor, Menu > Board Setup... > Physical Stackup.

The number after = specifies the width in pixels and is optional.

Layer Exports

To export specific PCB layers, use the following syntax:

![{F.Cu,F.Mask}](images/top-copper.png)
![{B.Cu,B.Mask}](images/bottom-copper.png =350)

Layer colors are determined by the KiCAD theme. Any installed KiCAD theme can be used, and is defined in the frontmatter using kicad_theme.
Multiple layers can be combined by separating them with commas. The order they appear in the list matters: the first layer will be on the bottom, the second will be above the first and so on. This allows the layers to show details without being covered by other layers, ie. F.Silkscreen as the last layer will put it on top of all other layers.
In KiCAD, layers can be renamed, ie User.2 might be renamed to Dimension. KiCAD doesn’t recognize the new name, so make sure the original layer name is used in the markdown.
File structure will be automatically created. In this example the images folder will be created in the same folder as the markdown file.
=350 is an optional parameter that sets the width of the image in pixels. Height can also be specified with =350x350.

3D Renders

To include 3D renders of your PCB:

![{Render/top/0/0/0}](images/3d-top.png =350x350)
![{Render/bottom/180/0/0}](images/3d-bottom.png)

The render syntax is: {Render/view/x/y/z} where:

view: bottom, left, right, front, or back
x,y,z: rotation angles in degrees

The render will use the KiCAD preset view Follow PCB Editor. If a layer is not visible in the PCB Editor, that layer will not be rendered.

width and height can also be specified with =350x350.

Drill Map

There are two options for drill maps:

![{Drill}](images/drills.png) will create a drill map from the PCB file
Exporting an SVG or DXF file from KiCAD, then importing it into a layer and exporting it as described above

If you use the {Drill} method, you’ll always have an updated map and not have to manually do it. You lose some control over how it appears. KiCAD doesn’t generate the images using a theme, so it will always be black/white.

Custom CSS

You can use a custom CSS stylesheet by adding the stylesheet option to the frontmatter. Here’s an example:

body.light-mode {
    --color-text: #1a1a1a;              /* Main text color */
    --color-background: #ffffff;        /* Document background color */
    --color-border: #e0e0e0;            /* Border color for elements */
    --color-accent: #0366d6;            /* Accent color for links and highlights */
    --color-image-background: #ffffff;  /* Background color for images */
    --title-block-text: #1a1a1a;        /* Text color in the title block */
}

body.dark-mode {
    --color-text: #ffffff;              /* Main text color */
    --color-background: #1a1a1a;        /* Document background color */
    --color-border: #444444;            /* Border color for elements */
    --color-accent: #58a6ff;            /* Accent color for links and highlights */
    --color-image-background: #1a1a1a;  /* Background color for images */
    --title-block-text: #ffffff;        /* Text color in the title block */
}

More variables can be found by inspecting the CSS in the browser.

UML Diagrams

You can include UML diagrams using PlantUML syntax:

```plantuml
@startuml
!theme reddress-darkblue
participant Controller
participant "I2C Bus" as Bus
participant Target

Controller -> Bus : Start Condition
Bus -> Target: Forward Address Frame (7-bit Addr + Read Bit)

Target-> Bus : ACK
Bus -> Controller: ACK
@enduml
    ```

Produces:

A list of themes can be found here

Code Highlighting

Code blocks are syntax-highlighted:

```cpp:optional_name.cpp
void app_main(void)
{
    printf("typecad-docgen");
}
    ```

Produces:

void app_main(void)
{
    printf("typecad-docgen");
}optional_name.cpp

You can change the theme to any listed here: https://shiki.style/themes.

A filename can be given by adding :<filename> to the end of the language name.

Math

Some text with inline AsciiMath $a^{2} + b^{2} = c^{2}$ ( $a^2 + b^2 = c^2$ ) and inline LaTeX math $\sin θ$ ($\sin \theta$) is possible.

AsciiMath blocks:

e = \sum_{n = 0}^{\infty} \frac{1}{n!}

$$
e = sum_(n=0)^oo 1 / n!
$$

And LaTeX blocks:

e = \sum_{n = 0}^{\infty} \frac{1}{n!}

\[
e = \sum_{n=0}^{\infty} \frac{1}{n!}
\]

Task Lists

Task 1
Task 2
Task 3

- [x] Task 1
- [ ] Task 2
- [ ] Task 3

Alerts

Note

GitHub Style Alerts/Admonitions

> [!NOTE]
> Highlights information that users should take into account.

> [!TIP]
> Optional information to help a user.

> [!IMPORTANT]
> Crucial information.

> [!WARNING]
> Critical content demanding immediate user attention.

> [!CAUTION]
> Negative potential consequences of an action.

Common Issues

KiCad Not Found: Ensure KiCad is installed and accessible in your system PATH or in the default installation directory
Image Generation Fails: Check if you have write permissions in the output directory
Layer Not Found: Verify the layer name matches exactly with KiCad layer names, not renamed layers, but the original default names (User.1, User.2, etc.)

Support

For more information and updates, visit:

Website: https://typecad.net
Support: https://www.buymeacoffee.com/typecad

Company	typeCAD	Board Name	usage-guide	Variant	released	Sheet	1 of 1
Filename	./build/atmos.kicad_pcb	Revision	1	Date	3/25/2025