How to Embed SVG Schematics from KiCad into a Hugo Page

I have recently decided to move Infinus Electronics over to Hugo, as WordPress with its weird styling issues and super hard to understand file structure made it way too frustrating to debug and customise. So far, working with Hugo has been a blast, and having worked with frameworks like Laravel and Flask before, the whole organisation of pages by file hierarchy has been a lot more intuitive.

And transparent.

The issue

My first post written on this new platform is the Battery Powered +48V Phantom Power Supply , which of course, had to show a schematic from KiCad.

Now, of course, one could just embed the SVG generated by KiCad using the figure shortcode or something similar. The thing is, that sticks a bright, honking blob smack in the middle of my slick dark mode theme, and I wasn’t about to ruin this aesthetic just yet.

The solution was to find a way to directly embed the KiCad SVG into the site, then somehow use some CSS class shenanigans to modify the colors when the theme switches.

The solution

Clean up the SVG in Adobe Illustrator

This is very important, since generally, the schematics directly off KiCad have a way oversized background as KiCad just exports the entire sheet, and for whatever reason Hugo does weird stuff the the SVG coordinates if you try to embed the SVG without this step. Also, due to the units and sizes used, the schematic overflows hopelessly.

Export the SVG from KiCad, and be sure to:

Use the KiCad Default color scheme
Export with background to avoid the final file being transparent

Then, resize the artboard and background to an appropriate size in Illustrator.

Export the file as SVG, using the Export As function and not just plain saving, although just directly saving it should work too.

In the Export As dialog:

Select Internal CSS for the styling. This is paramount, as it creates style tags with CSS variables that we can easily modify
The other settings shouldn’t really matter, but you probably want to check Minify as well

Change all the color values to CSS variables

This allows us to easily modify them by adding the appropriate classes for both the dark and the light themes to a stylesheet.

It changes all the original color hex values to variables that we can modify from somewhere else

Here is the Python script to do so:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
"""
This dude takes an ADOBE ILLUSTRATOR cleaned up KiCad SVG, and applies all the magic to make it all fancy and dark theme-y

Export instructions:
In KiCad 6.0, export svg with background and using KiCad Default

Go to Illustrator, crop the Artboard and do what you have to do
Then export as svg, styling use INTERNAL CSS, other settings shouldn't really matter

Then, run this script

"""

import sys

from tempfile import mkstemp
from shutil import copymode, move
from os import fdopen, remove

from tkinter import Tk
from tkinter.filedialog import askopenfilename
from tkinter.messagebox import showinfo

Tk().withdraw()

try:
    old_file_path = sys.argv[1]
except IndexError:
    old_file_path = askopenfilename()

# creating a variable and storing the text
# that we want to search
# also handle lowercases
search_text = ["#F5F4EF", "#840000", "#A90000", "#009600", "#006464", "#FFFFC2", "#f5f4ef", "#840000", "#a90000", "#009600", "#006464", "#ffffc2"]

# creating a variable and storing the text
# that we want to add
replace_text = ["var(--scm-bg)", "var(--scm-lred)", "var(--scm-red)", "var(--scm-green)", "var(--scm-cyan)", "var(--scm-yellow)", "var(--scm-bg)", "var(--scm-lred)", "var(--scm-red)", "var(--scm-green)", "var(--scm-cyan)", "var(--scm-yellow)"]

# Opening our text file in read only
# mode using the open() function
with open(old_file_path, 'r') as file:

    # Reading the content of the file
    # using the read() function and storing
    # them in a new variable
    data = file.read()

    # Searching and replacing the text
    # using the replace() function
    for search_text, replace_text in zip(search_text, replace_text):

        data = data.replace(search_text, replace_text)

# Opening our text file in write only
# mode to write the replaced content
with open(old_file_path, 'w') as file:

    # Writing the replaced data in our
    # text file
    file.write(data)

# Printing Text replaced
print("CSS should now be fixed")
showinfo(title="Infinus Electronics Shenanigans", message="CSS for schematic should now be fixed")

When you run this script, a prompt appears. Select your SVG file, and the script should handle the rest.

Note that doing so will cause the SVG to not be openable in any app, since all the color information is effectively removed.

Please do tinker with this script, I wrote it in a hurry based off this other guide of mine on including Jupyter notebooks in Wordpress , so it’s super hacky and crude. Yes, I copied a lot of it from various online sources.

schematic.css

Note: I am using the PaperMod theme for Hugo. If you’re using something else, the original class names might be different, so you will need to do some sleuthing

Next, we need to create a stylesheet to tell the browser what colors to actually use. Here is where you can pat yourself on the back, and have some fun (or not) in picking colors that you like.

Under \assets\css\extended create a new file schematics.css (file name does not matter, call it whatever you like)

Then, this is what I have for this site (at the time of writing):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
/* Normal KiCad */

svg{ 

    --scm-green: #00a900;
    --scm-cyan: #006464;
    --scm-red: #911717;
    --scm-lred: #6b0808;
    --scm-bg: #f5f4ef;
    --scm-yellow: #ffffc2;
    border-radius: var(--radius);

}

/* Dark Mode KiCad */

.dark svg{ 

    --scm-green: #72e28a;
    --scm-cyan: #b8eaea;
    --scm-red: #e6d071;
    --scm-lred: #ef7575;
    --scm-yellow: #817933;
    --scm-bg: var(--entry);

}

.kicad-schematic:hover {

    transform: scale(1.2);
    
}

.kicad-schematic {

    transition: 100ms all ease;
    /* margin-top: 10px; */
    margin-bottom: var(--content-gap);

}

The svg and .dark svg classes each define the colors that show up on the schematic itself. This is where you would make adjustments to tailor the schematic according to your liking.

The other stuff is a hacky zoom on hover thing that I just slapped together. It is quite bad, so it’ll likely not remain for much longer. I thought I’d include it here just because. I also adjsuted the margins so that everything would remain consistent.

KiCad schematic shortcode

In Hugo, the way you insert functions that do cool stuff into your .md files is by using shortcodes.

Here is one I came up with to insert a KiCad Schematic SVG file that has been processed:

1
2
3
4
5
6
{{$src := .Get 0}}

<div class="kicad-schematic">    
    {{$s := .Page.Resources.GetMatch $src}}
    {{$s.Content | safeHTML}}
</div>

Basically what this does, is it creates a div element with the class name kicad-schematic, which makes sure the right CSS classes get applied. Then, it directly embeds the content of the SVG file as a child of the div, after passing it through safeHTML to avoid escaping all the quote marks and brackets and stuff.

Usage

To use it, in your page .md file, insert the shortcode as follows:

{{< kicad_schematic  "path_to_svg" >}}

So in the case of the Battery Powered +48V Phantom Power Supply page bundle , the code was:

{{< kicad_schematic "Phantom Power Supply.svg" >}}

Fun aside: if you want to embed Hugo shortcodes without actually running them, comment out the innards of the pointy brackets.

So like the above examples, I had {{~</* kicad_schematic "Phantom Power Supply.svg" */>}}, but without the tilde (~). The tilde is there because if it were not, Hugo removes the /* and you’d be really confused indeed.

Conclusion

And there we have it, all that work, for a schematic that changes color in dark mode…

Todos

There are still some stuff that I’d like to implement, and I’d update this post when I get around to implementing them:

Write a script so that people without Adobe Illustrator can do the same thing.
Right now, the image is really, really small; not great for readability. I want to implement a less hacky hover zoom.
Add a button under the embedded SVG that would allow someone to download a raw file that has not been modified by the Python script.
Maybe get Hugo to do the conversion automatically? Like how it processes images.
Extend this functionality to implement a KiCad PCB viewer that allows the user to toggle each layer on and off, that’d be epic!

The issue#

The solution#

Clean up the SVG in Adobe Illustrator#

Change all the color values to CSS variables#

schematic.css#

KiCad schematic shortcode#

Usage#

Conclusion#

Todos#