Contributor & Authoring Guide

(Updated: Aug 27, 2026)

Welcome to the Cadiora Contributor & Authoring Guide! This page serves as a live reference for anyone planning to write, structure, or submit articles to Cadiora.

Here you will find our content organization guidelines, front matter conventions, diagram engines, and a complete showcase of every custom shortcode supported by the theme.

1. Content Organization & Workflow

Articles on Cadiora use Hugo Page Bundles. Each article lives in its own folder under content/articles/<category>/<article-name>/.

Directory Structure

content/articles/diodes/avalanche_diode/
├── index.md                 # 📄 Main article content (Published)
├── images/                  # 🖼️ Article images (Published)
│   └── diagram.png
├── .notes.md                # 📝 Personal author notes (Ignored by Hugo)
└── research/                # 🔬 Research materials (Ignored by Hugo)
    ├── notes.md             # Research notes & findings
    ├── citations.md         # Bibliography & references
    └── papers/              # Reference PDFs and datasheets

[!NOTE]
Files matching .notes.md, README.md, or inside research/ directories are automatically ignored by Hugo during site generation. You can keep your background research and drafts committed safely in Git without them publishing to the live site.

2. Front Matter Reference

Every article must start with a YAML front matter block. Below is the standard template:

---
title: "Introduction to Avalanche Diodes"
date: 2026-08-27
author: "Your Name"
summary: "A deep dive into the avalanche breakdown mechanism, operating principles, and circuit applications."
categories: ["Electronics", "Semiconductors"]
tags: ["diodes", "avalanche", "pn-junction", "breakdown"]
level: "Intermediate"        # Beginner | Intermediate | Advanced
series: "Semiconductor Fundamentals"
weight: 1
draft: false
coverImage: "images/cover.jpg"
featured: false
mermaid: true                # Set to true if article uses Mermaid diagrams
wavedrom: true               # Set to true if article uses WaveDrom diagrams
---

3. Diagram Engines

Cadiora supports both WaveDrom for digital timing / hardware signals and Mermaid for software architecture, flowcharts, and mindmaps.

3.1 WaveDrom (Digital Timing & Bus Diagrams)

Set wavedrom: true in your front matter. Then write WaveDrom JSON inside fenced code blocks using ```wavedrom.

```wavedrom
{
  "signal": [
    { "name": "CLK",  "wave": "p.....|..." },
    { "name": "DATA", "wave": "x.3.4.5.x.", "data": ["ADDR", "READ", "ACK"] },
    { "name": "REQ",  "wave": "0.1...0..." },
    { "name": "BUSY", "wave": "0..1.0...." }
  ],
  "head": {
    "text": "Figure: Read Request Handshake Protocol",
    "tick": 0
  }
}
```

3.2 Mermaid (Flowcharts, State Machines & Mindmaps)

Set mermaid: true in your front matter. You can use standard ```mermaid code fences or the {{&#60; mermaid-mindmap &#62;}} shortcode.

Flowchart / State Diagram

graph TD
    A[Input Signal] --> B{Threshold Exceeded?}
    B -- Yes --> C[Trigger Avalanche Multiplication]
    B -- No --> D[Normal Reverse Saturation]
    C --> E[Breakdown Region]
    D --> F[Low Leakage Current]

```mermaid
graph TD
    A[Input Signal] --> B{Threshold Exceeded?}
    B -- Yes --> C[Trigger Avalanche Multiplication]
    B -- No --> D[Normal Reverse Saturation]
    C --> E[Breakdown Region]
    D --> F[Low Leakage Current]
```

4. Theme Shortcodes Reference

4.1 Info Boxes (info-box)

Use info boxes to draw attention to notes, tips, warnings, or essential context.

Supported types: info (default), tip, warning, note

Live Preview:

Informational Note: This is a general informational box highlighting a key concept.
Pro Tip: Always verify reverse breakdown voltage ratings under operating junction temperatures.
Caution: Exceeding maximum dissipation power will result in thermal runaway and irreversible damage.
Reference: Note that Zener breakdown dominates below 5V, while Avalanche breakdown dominates above 7V.

Markdown Syntax:

{{< info-box type="info" >}}
**Informational Note:** This is a general informational box highlighting a key concept.
{{< /info-box >}}

{{< info-box type="tip" >}}
**Pro Tip:** Always verify reverse breakdown voltage ratings under operating junction temperatures.
{{< /info-box >}}

{{< info-box type="warning" >}}
**Caution:** Exceeding maximum dissipation power will result in thermal runaway.
{{< /info-box >}}

{{< info-box type="note" >}}
**Reference:** Note that Zener breakdown dominates below 5V.
{{< /info-box >}}

4.2 Interactive Tabs (tabs & tab)

Use tabs to group code across multiple languages, compare before/after configurations, or toggle between code and preview.

Live Preview:

def calculate_breakdown_current(v_applied, v_breakdown, n=3):
    """Simple empirical model for avalanche multiplication factor."""
    if v_applied < v_breakdown:
        m = 1 / (1 - (v_applied / v_breakdown) ** n)
        return m
    return float('inf')
#include <cmath>
#include <limits>

double calculateBreakdownCurrent(double vApplied, double vBreakdown, double n = 3.0) {
    if (vApplied < vBreakdown) {
        return 1.0 / (1.0 - std::pow(vApplied / vBreakdown, n));
    }
    return std::numeric_limits<double>::infinity();
}

Markdown Syntax:

```markdown
{{< tabs >}}
  {{< tab name="Python" >}}
```python
def calculate_breakdown_current(v_applied, v_breakdown, n=3):
    return 1 / (1 - (v_applied / v_breakdown) ** n)
```
  {{< /tab >}}
  {{< tab name="C++" >}}
```cpp
double calculateBreakdownCurrent(double vApplied, double vBreakdown, double n = 3.0) {
    return 1.0 / (1.0 - std::pow(vApplied / vBreakdown, n));
}
```
  {{< /tab >}}
{{< /tabs >}}
```

4.3 Tooltip (tooltip)

Add interactive hover tooltips with optional titles or icons to explain complex jargon without disrupting reading flow.

Live Preview:

When a strong reverse bias is applied to a p-n junctionP-N JunctionThe boundary or interface between two types of semiconductor material (p-type and n-type). , high electric field gradients accelerate free carriers into initiating impact ionizationImpact IonizationThe process where high-energy electrons collide with crystal atoms to generate electron-hole pairs. .

Markdown Syntax:

When a strong reverse bias is applied to a {{< tooltip text="p-n junction" title="P-N Junction" >}}The boundary or interface between two types of semiconductor material (p-type and n-type).{{< /tooltip >}}, high electric field gradients accelerate free carriers into initiating {{< tooltip text="impact ionization" title="Impact Ionization" >}}The process where high-energy electrons collide with crystal atoms to generate electron-hole pairs.{{< /tooltip >}}.

4.4 Grid & Cards (grid & card)

Create responsive 2-column or 3-column card layouts with optional images and customizable orientations.

Live Preview:

Avalanche Mode
Operates above the breakdown threshold where carrier impact ionization creates multiplication.
Zener Mode
Operates via quantum mechanical tunneling through a heavily doped narrow depletion barrier.

Markdown Syntax:

{{< grid cols="1" md="2" gap="4" >}}
{{< card title="Avalanche Mode" >}}
Operates above the breakdown threshold where carrier impact ionization creates multiplication.
{{< /card >}}
{{< card title="Zener Mode" >}}
Operates via quantum mechanical tunneling through a heavily doped narrow depletion barrier.
{{< /card >}}
{{< /grid >}}

4.5 Timeline (timeline & timeline-item)

Display chronological sequences, historical milestones, or multi-step engineering roadmaps.

Live Preview:

  1. 1. Literature Review & Research

    Gather datasheets, academic publications, and draft the initial hypothesis.

  2. 2. Simulation & Modeling

    Run SPICE models to simulate the breakdown current characteristics.

  3. 3. Article Draft & Peer Review Current

    Write the markdown article, add WaveDrom diagrams, and submit for review.

Markdown Syntax:

{{< timeline style="vertical" >}}
{{< timeline-item title="1. Literature Review & Research" date="Phase 1" description="Gather datasheets, academic publications, and draft the initial hypothesis." >}}
{{< timeline-item title="2. Simulation & Modeling" date="Phase 2" description="Run SPICE models to simulate the breakdown current characteristics." >}}
{{< timeline-item title="3. Article Draft & Peer Review" date="Phase 3" description="Write the markdown article, add WaveDrom diagrams, and submit for review." tag="Current" >}}
{{< /timeline >}}

4.6 Buttons (button)

Create styled call-to-action buttons for external resources, downloads, or cross-article links.

Live Preview:

Browse All Articles About Cadiora

Markdown Syntax:

{{< button href="/articles/" primary=true >}}Browse All Articles{{< /button >}}
{{< button href="/brand/" primary=false >}}About Cadiora{{< /button >}}

4.7 YouTube Embed (youtube)

Embed responsive, privacy-enhanced YouTube videos (youtube-nocookie.com).

{{< youtube id="dQw4w9WgXcQ" title="Demo Video Tutorial" >}}

4.8 Responsive Figures (figure)

Render optimized responsive pictures with captions:

{{< figure src="images/avalanche_doping_vs_width.png" alt="Doping Concentration vs Depletion Width" caption="Figure 1: Depletion width as a function of donor doping concentration." >}}

5. KaTeX Math & Code Blocks

5.1 Inline and Block Math

Goldmark passthrough is enabled for standard LaTeX math syntax:

  • Inline Math: Use single dollar signs $ ... $.
    Example: The multiplication factor is given by $M = \frac{1}{1 - (V/V_B)^n}$.

  • Display Block Math: Use double dollar signs $$ ... $$ or ```math blocks:

$$ I = M \cdot I_0 = \frac{I_0}{1 - \left(\frac{V_R}{V_{BR}}\right)^n} $$

5.2 Syntax Highlighting

Cadiora uses Chroma for fast, accessible syntax highlighting with automatic copy buttons on all code blocks:

module clock_divider (
    input  wire clk_in,
    input  wire reset_n,
    output reg  clk_out
);
    always @(posedge clk_in or negedge reset_n) begin
        if (!reset_n)
            clk_out <= 1'b0;
        else
            clk_out <= ~clk_out;
    end
endmodule

6. Article Submission Checklist

Before submitting an article for review, ensure:

  • All front matter fields (title, summary, categories, tags, level) are properly populated.
  • If using WaveDrom diagrams, wavedrom: true is included in the front matter.
  • If using Mermaid diagrams, mermaid: true is included in the front matter.
  • Images are placed in the local images/ directory within the page bundle.
  • Equations render correctly with matching $ or $$ delimiters.
  • Private notes and PDFs are placed under .notes.md or research/ to prevent accidental publication.