Look and Feel

Customize colors, fonts, and more for your site.

By default, a site using Docsy has the theme’s default fonts, colors, and general look and feel. However, if you want your own color scheme (and you probably will!) you can very easily override the theme defaults with your own project-specific values - Hugo will look in your project files first when looking for information to build your site. Also because Docsy uses Bootstrap 4 and SCSS for styling, you can override just single values in its special SCSS project variables file, or do more serious customization by creating your own versions of entire SCSS files.

Color palette and other styles

To quickly change your site’s colors, add SCSS variable project overrides to assets/scss/_variables_project.scss. A simple example changing the primary and secondary color to two shades of purple:

$primary: #390040;$secondary: #A23B72;


The theme has features such as rounded corners and gradient backgrounds enabled by default. These can also be toggled in your project variables file:

$enable-gradients: true;$enable-rounded: true;
$enable-shadows: true;  Also note that any SCSS import will try the project before the theme, so you can – as one example – create your own _assets/scss/_content.scss and get full control over how your Markdown content is styled. Fonts The theme uses Open Sans as its primary font. To disable Google Fonts and use a system font, set this SCSS variable in assets/scss/_variables_project.scss: $td-enable-google-fonts: false;


$google_font_name: "Open Sans";$google_font_family: "Open+Sans:300,300i,400,400i,700,700i";


right = "$" display = false [[params.katex.options.delimiters]] left = "\$$" right = "\$$" display = false [[params.katex.options.delimiters]] left = "\$" right = '\$' display = true  For a complete list of options and their detailed description, have a look at the documentation of $${\KaTeX}’s$$ Rendering API options and of $${\KaTeX}’s$$ configuration options. Display of Chemical Equations and Physical Units mhchem is a $$\LaTeX$$ package for typesetting chemical molecular formulae and equations. Fortunately, $$\KaTeX$$ provides the mhchem extension that makes the mhchem package accessible when authoring content for the web. Since this extension was integrated into the Docsy theme, you can write beautiful chemical equations easily once mhchem support is enabled inside your config.toml: [params.katex] enable = true [params.katex.mhchem] enable = true  With mhchem extension enabled, you can easily include chemical equations into your page. The equations can be shown either inline or can reside on its own line. The following code sample produces a text line including a chemical equation: *Precipitation of barium sulfate:* \$$\ce{SO4^2- + Ba^2+ -> BaSO4 v}\$$  Precipitation of barium sulfate: $$\ce{SO4^2- + Ba^2+ -> BaSO4 v}$$ More complex equations, like the one shown in the code sample below, should be displayed on their own line: $$\tag*{(2)} \ce{Zn^2+ <=>[+ 2OH-][+ 2H+] \underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}} <=>[+ 2OH-][+ 2H+] \underset{\text{tetrahydroxozincate}}{\ce{[Zn(OH)4]^2-}}}$$  $$\tag*{(2)} \ce{Zn^2+ <=>[+ 2OH-][+ 2H+] \underset{\text{amphoteric hydroxide}}{\ce{Zn(OH)2 v}} <=>[+ 2OH-][+ 2H+] \underset{\text{tetrahydroxozincate}}{\ce{[Zn(OH)4]^2-}}}$$ Use of mhchem is not limited to the authoring of chemical equations, using the included \pu command, pretty looking physical units can be written with ease, too. The following code sample produces two text lines with four numbers plus their corresponding physical units: * Scientific number notation: \$$\pu{1.2e3 kJ}\$$ or \$$\pu{1.2E3 kJ}\$$ \\ * Divisions: \$$\pu{123 kJ/mol}\$$ or \$$\pu{123 kJ//mol}\$$  • Scientific number notation: $$\pu{1.2e3 kJ}$$ or $$\pu{1.2E3 kJ}$$ • Divisions: $$\pu{123 kJ/mol}$$ or $$\pu{123 kJ//mol}$$ For a complete list of options when authoring physical units, have a look at the section on physical units in the mhchem documentation. Diagrams with Mermaid Mermaid is a Javascript library for rendering simple text definitions to useful diagrams in the browser. It can generate a variety of different diagram types, including flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, user journey diagrams, Gantt charts and pie charts. With Mermaid support enabled in Docsy, you can include the text definition of a Mermaid diagram inside a code block, and it will automatically be rendered by the browser as soon as the page loads. The great advantage of this is anyone who can edit the page can now edit the diagram - no more hunting for the original tools and version to make a new edit. For example, the following defines a simple flowchart: mermaid graph LR Start --> Need{"Do I need diagrams"} Need -- No --> Off["Set params.mermaid.enable = false"] Need -- Yes --> HaveFun["Great! Enjoy!"]   Automatically renders to: graph LR Start --> Need{"Do I need diagrams"} Need -- No --> Off["Set params.mermaid.enable = false"] Need -- Yes --> HaveFun["Great! Enjoy!"]  To enable/disable Mermaid, update config.toml: [params.mermaid] enable = true  You also need to disable the guessSyntax from markup highlighting in config.toml for Mermaid to work: [markup] [markup.highlight] guessSyntax = "false"  You can also update settings for Mermaid, such as themes, padding, etc: [params.mermaid] enable = true theme = "neutral" [params.mermaid.flowchart] diagramPadding = 6  See the Mermaid documentation for a list of defaults that can be overridden. Settings can also be overridden on a per-diagram basis by making use of the %%init%% header at the start of the diagram definition. See the Mermaid theming documentation. UML Diagrams with PlantUML PlantUML is an alternative to Mermaid that lets you quickly create UML diagrams, including sequence diagrams, use case diagrams, and state diagrams. Unlike Mermaid diagrams, which are entirely rendered in the browser, PlantUML uses a PlantUML server to create diagrams. You can use the provided default demo server (not recommended for production use), or run a server yourself. PlantUML offers a wider range of image types than Mermaid, so may be a better choice for some use cases. Diagrams are defined using a simple and intuitive language. (see PlantUML Language Reference Guide). The following example shows a use case diagram: plantuml participant participant as Foo actor actor as Foo1 boundary boundary as Foo2 control control as Foo3 entity entity as Foo4 database database as Foo5 collections collections as Foo6 queue queue as Foo7 Foo -> Foo1 : To actor Foo -> Foo2 : To boundary Foo -> Foo3 : To control Foo -> Foo4 : To entity Foo -> Foo5 : To database Foo -> Foo6 : To collections Foo -> Foo7: To queue   Automatically renders to: participant participant as Foo actor actor as Foo1 boundary boundary as Foo2 control control as Foo3 entity entity as Foo4 database database as Foo5 collections collections as Foo6 queue queue as Foo7 Foo -> Foo1 : To actor Foo -> Foo2 : To boundary Foo -> Foo3 : To control Foo -> Foo4 : To entity Foo -> Foo5 : To database Foo -> Foo6 : To collections Foo -> Foo7: To queue  To enable/disable PlantUML, update config.toml: [params.plantuml] enable = true  Other optional settings are: [params.plantuml] enable = true theme = "default" #Set url to plantuml server #default is http://www.plantuml.com/plantuml/svg/ svg_image_url = "https://www.plantuml.com/plantuml/svg/"  MindMap support with MarkMap MarkMap is a Javascript library for rendering simple text definitions to MindMap in the browser. For example, the following defines a simple MindMap: markmap # markmap ## Links - <https://markmap.js.org/> - [GitHub](https://github.com/gera2ld/markmap) ## Related - [coc-markmap](https://github.com/gera2ld/coc-markmap) - [gatsby-remark-markmap](https://github.com/gera2ld/gatsby-remark-markmap) ## Features - links - **inline** ~~text~~ *styles* - multiline text - inline code - js console.log('code block');  - Katex -$x = {-b \pm \sqrt{b^2-4ac} \over 2a}$  Automatically renders to: # markmap ## Links - <https://markmap.js.org/> - [GitHub](https://github.com/gera2ld/markmap) ## Related - [coc-markmap](https://github.com/gera2ld/coc-markmap) - [gatsby-remark-markmap](https://github.com/gera2ld/gatsby-remark-markmap) ## Features - links - **inline** ~~text~~ *styles* - multiline text - inline code - js console.log('code block');  - Katex -$x = {-b \pm \sqrt{b^2-4ac} \over 2a}\$


To enable/disable MarkMap, update config.toml:

[params.markmap]
enable = true


Customizing templates

If you need to add some code (CSS import, cookie consent, or similar) to the head section on every page, add the head-end.html partial to your project:

layouts/partials/hooks/head-end.html


And add the code you need in that file. Your partial code is automatically included just before the end of the theme partial head.html. The theme version of head-end.html is empty.

Similarly, if you want to add some code right before the body end, create your own version of the following file:

layouts/partials/hooks/body-end.html


Any code in this file is included automatically at the end of the theme partial scripts.html.

Both head.html and scripts.html are then used to build Docsy’s base page layout, which is used by all the other page templates:

<!doctype html>
<html lang="{{ .Site.Language.Lang }}" class="no-js">
<body class="td-{{ .Kind }}">
{{ partial "navbar.html" . }}