README Files

Paplix renders README files with enhanced support for KiCad projects.

Overview

Each repository can have a README.md file that's displayed on the repository overview page. Paplix extends standard Markdown with KiCad-specific features.

Standard Markdown

Paplix supports all GitHub-Flavored Markdown (GFM) features:

  • Headings - # H1, ## H2, ### H3
  • Bold and Italic - **bold**, *italic*
  • Lists - Ordered and unordered
  • Links - [text](url)
  • Images - ![alt](url)
  • Code - Inline and fenced code blocks
  • Tables - Standard Markdown tables
  • Blockquotes - > quoted text

Component References

Reference schematic components directly in your README using the @ syntax:

The power section uses @R1 and @C1 for filtering.
Check @U3 for the main controller.

When rendered, component references like @R1, @C4, or @U3 become interactive:

  • Hover to see component details
  • Click to navigate to the component in the schematic viewer

Supported Designators

  • R - Resistors (@R1, @R42)
  • C - Capacitors (@C1, @C10)
  • L - Inductors (@L1)
  • U - ICs (@U1, @U3)
  • Q - Transistors (@Q1)
  • D - Diodes (@D1)
  • J - Connectors (@J1)
  • And more: S, K, F, M, T, P, X, Y, Z, A, B, W

KiCad File Previews

Link to KiCad files in your README to show embedded previews:

See the main schematic: [main.kicad_sch](./main.kicad_sch)

View the PCB layout: [board.kicad_pcb](./board.kicad_pcb)

When you link to .kicad_sch or .kicad_pcb files:

  • A thumbnail preview is shown inline
  • Click to open the full schematic/PCB viewer
  • Changes in the file are reflected in the preview

Creating a README

From the Web Interface

  1. Navigate to your repository
  2. Click on the Overview tab
  3. Click Add README or Edit README
  4. Use the split-view editor to write and preview
  5. Click Save & Commit

From KiCad Plugin

  1. Create a README.md file in your project directory
  2. Edit it with any text editor
  3. Sync your changes with Paplix

Best Practices

Structure Your README

A good README includes:

  1. Project Title - What is this project?
  2. Description - Brief overview of the circuit
  3. Features - Key specifications
  4. Getting Started - How to use or build it
  5. Component References - Use @designators for key parts

Example README

# USB Power Supply

A USB-C power delivery board supporting up to 100W.

## Features

- USB-C PD 3.0 compliant
- 5V/9V/12V/20V output
- Over-current protection via @F1

## Key Components

- @U1 - USB-C PD controller
- @U2 - Buck converter
- @C1, @C2 - Input filtering

## Schematic

See [power-supply.kicad_sch](./power-supply.kicad_sch)

Tips

  • Use component references to make documentation actionable
  • Link to schematic files for visual context
  • Keep the README updated as your design evolves
  • Use headings to organize sections clearly

Next Steps