<linkhref="https://McShelby.github.io/hugo-theme-relearn/basics/customization/index.html"rel="canonical"type="text/html"title="Customization :: Hugo Relearn Theme">
<p>The Relearn theme has been built to be as configurable as possible by defining multiple <ahref="https://gohugo.io/templates/partials/"target="_blank">partials</a></p>
<p>In <code>themes/hugo-theme-relearn/layouts/partials/</code>, you will find all the partials defined for this theme. If you need to overwrite something, don’t change the code directly. Instead <ahref="https://gohugo.io/themes/customizing/"target="_blank">follow this page</a>. You’d create a new partial in the <code>layouts/partials</code> folder of your local project. This partial will have the priority.</p>
<li><code>header.html</code>: the header of the page. See <ahref="#output-formats">output-formats</a></li>
<li><code>footer.html</code>: the footer of the page. See <ahref="#output-formats">output-formats</a></li>
<li><code>body.html</code>: the body of the page. The body may contain of one or many articles. See <ahref="#output-formats">output-formats</a></li>
<li><code>article.html</code>: the output for a single article, can contain elements around your content. See <ahref="#output-formats">output-formats</a></li>
<li><code>menu.html</code>: left menu. <em>Not meant to be overwritten</em></li>
<li><code>search.html</code>: search box. <em>Not meant to be overwritten</em></li>
<li><code>custom-header.html</code>: custom headers in page. Meant to be overwritten when adding CSS imports. Don’t forget to include <code>style</code> HTML tag directive in your file.</li>
<li><code>custom-footer.html</code>: custom footer in page. Meant to be overwritten when adding JavaScript. Don’t forget to include <code>javascript</code> HTML tag directive in your file.</li>
<li><code>heading-pre.html</code>: side-wide configuration to prepend to pages title headings. If you override this, it is your responsibility to take the page’s <code>headingPre</code> setting into account.</li>
<li><code>heading-post.html</code>: side-wide configuration to append to pages title headings. If you override this, it is your responsibility to take the page’s <code>headingPost</code> setting into account.</li>
<li><code>menu-pre.html</code>: side-wide configuration to prepend to menu items. If you override this, it is your responsibility to take the page’s <code>menuPre</code> setting into account.</li>
<li><code>menu-post.html</code>: side-wide configuration to append to menu items. If you override this, it is your responsibility to take the page’s <code>menuPost</code> setting into account.</li>
<li><code>content.html</code>: the content page itself. This can be overridden if you want to display page’s meta data above or below the content.</li>
<p>If your favicon is a SVG, PNG or ICO, just drop off your image in your local <code>static/images/</code> folder and name it <code>favicon.svg</code>, <code>favicon.png</code> or <code>favicon.ico</code> respectively.</p>
<p>Additionally, if you want your site to use light & dark theme favicons that follow the OS’ (and in some cases, the browser’s) color scheme, add the image files to your local <code>static/images/</code> folder and name them eg. <code>favicon-light.svg</code> and/or <code>favicon-dark.svg</code> respectively corresponding to your file format. In case one of the files is missing, the theme falls back to eg. <code>favicon.svg</code> for the missing file. All supplied favicons must be of the same file format.</p>
<p>IE and old browser versions do not support <ahref="https://caniuse.com/css-media-interaction"target="_blank">media queries</a>, which are necessary for the light & dark theme favicon option.
If you have requirements to support IE and/or older browser versions, use one of the other options.</p>
<p>If no favicon file is found, the theme will lookup the alternative filename <code>logo</code> in the same location and will repeat the search for the list of supported file types.</p>
<p>If you need to change this default behavior, create a new file in <code>layouts/partials/</code> named <code>favicon.html</code>. Then write something like this:</p>
<divclass="wrap-code highlight"><pretabindex="0"class="chroma"><codeclass="language-html"data-lang="html"><spanclass="line"><spanclass="cl"><spanclass="p"><</span><spanclass="nt">link</span><spanclass="na">rel</span><spanclass="o">=</span><spanclass="s">"icon"</span><spanclass="na">href</span><spanclass="o">=</span><spanclass="s">"/images/favicon.bmp"</span><spanclass="na">type</span><spanclass="o">=</span><spanclass="s">"image/bmp"</span><spanclass="p">></span></span></span></code></pre></div><h2id="change-the-menu-width">Change the Menu Width</h2>
<p>The menu width adjusts automatically for different screen sizes.</p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Screen Width</th>
<th>Menu Width</th>
</tr>
</thead>
<tbody>
<tr>
<td>S</td>
<td>< 48rem</td>
<td>0</td>
</tr>
<tr>
<td>M</td>
<td>48rem - 60rem</td>
<td>14.375rem</td>
</tr>
<tr>
<td>L</td>
<td>>= 60rem</td>
<td>18.75rem</td>
</tr>
</tbody>
</table>
<p>The values for the screen width breakpoints aren’t configurable.</p>
<p>If you want to adjust the menu width you can define the following CSS variables in your <code>custom-header.html</code>. Note that <code>--MENU-WIDTH-S</code> doesn’t exist as the menu is always hidden for small screen sizes.</p>
</span></span><spanclass="line"><spanclass="cl"><spanclass="nx">themeVariant</span><spanclass="p">=</span><spanclass="s2">"relearn-light"</span></span></span></code></pre></div><p>In the above example your theme file has to be named <code>theme-relearn-light.css</code></p>
<p>You can also set multiple variants. In this case, the first variant is the default chosen on first view and a variant switch will be shown in the menu footer.</p>
<p>If you want to switch the syntax highlighting theme together with your color variant, generate a syntax highlighting stylesheet and configure your installation <ahref="https://gohugo.io/content-management/syntax-highlighting/"target="_blank">according to Hugo’s documentation</a>, and <code>@import</code> this stylesheet in your color variant stylesheet. For an example, take a look into <code>theme-relearn-light.css</code> and <code>config.toml</code> of the exampleSite.</p>
<h3id="adjust-to-os-settings">Adjust to OS Settings</h3>
<p>You can also cause the site to adjust to your OS settings for light/dark mode. Just set the <code>themeVariant</code> to <code>auto</code>. That’s it.</p>
<p>If you’ve set multiple variants, you can drop <code>auto</code> at any position, but usually it makes sense to set it in the first position and make it the default.</p>
</span></span><spanclass="line"><spanclass="cl"><spanclass="nx">themeVariant</span><spanclass="p">=</span><spanclass="p">[</span><spanclass="s2">"auto"</span><spanclass="p">,</span><spanclass="s2">"red"</span><spanclass="p">]</span></span></span></code></pre></div><p>If you don’t configure anything else, the theme will use <code>relearn-light</code> for light mode and <code>relearn-dark</code> for dark mode.</p>
<p>If you don’t like that, you can set <code>themeVariantAuto</code>. The first element is the variant for light mode, the second for dark mode</p>
<p>Once a variant is fully loaded, either initially or by switching the variant manually with the variant selector, the custom event <code>themeVariantLoaded</code> on the <code>document</code> will be dispatched. You can add an event listener and react to changes.</p>
</span></span></span><spanclass="line"><spanclass="cl"><spanclass="c1"></span><spanclass="p">});</span></span></span></code></pre></div><h3id="roll-your-own">Roll your Own</h3>
<p>If you are not happy with the shipped variants you can either copy and rename one of the shipped files from <code>themes/hugo-theme-relearn/static/css</code> to <code>static/css</code>, edit them afterwards to your liking in a text editor and configure the <code>themeVariant</code> parameter in your <code>config.toml</code> or just use the <ahref="../../basics/generator/">interactive variant generator</a>.</p>
<h2id="own-shortcodes-with-javascript-dependencies">Own Shortcodes with JavaScript Dependencies</h2>
<p>Certain shortcodes make use of additional JavaScript files. The theme only loads these dependencies if the shortcode is used. To do so correctly the theme adds management code in various files. To provide this behavior to the user and extending it for his own shortcodes this can be configured.</p>
<p>Say you want to add a shortcode <code>myshortcode</code> that also requires the <code>jquery</code> JavaScript library.</p>
<p>Add the dependency loader file <code>layouts/partials/dependencies/myshortcode.html</code>. The loader file will be appended to your header or footer, dependend on the <code>location</code> setting in your <code>config.toml</code>.</p>
<li>the <code>name</code> setting in your <code>config.toml</code> must match the key (that needs to be prefixed with a <code>has</code>) you used for the store in your <code>layouts/shortcodes/myshortcode.html</code>.</li>
<p>Certain parts of the theme can be changed for support of your own <ahref="https://gohugo.io/templates/output-formats/"target="_blank">output formats</a>. Eg. if you define a new output format <code>PLAINTEXT</code> in your <code>config.toml</code>, you can add a file <code>layouts/partials/header.plaintext.html</code> to change the way, the page header should look like for that output format.</p>
