Skip to content

Features

Jump to bottom
Francesco edited this page Sep 21, 2024 · 20 revisions

Home | Setup

Table of contents

1 Homepage

The homepage offers minimal customization options, you can specify an intro, a collection to display, and social icons.

1.1 Intro Section

By setting those two parameters in your hugo.toml config you can control the text to display after the header on the homepage. Note that the body is interpreted as markdown.

[params]
homeIntroTitle = 'Hi!'

homeIntroContent = """
I am an Italian Software Engineer with a strong foundation in computer science and a passion for solving complex problems. 
I am interested in a range of topics, including algorithms, distributed systems, databases, and information retrieval.
"""

Note that you can omit one of the two if you want.

1.2 Social Icons

You can include social icons after the intro like follows.

[[params.social]]
name = "linkedin"
url = "https://www.linkedin.com/in/user/"

[[params.social]]
name = "medium"
url = "https://medium.com/@user"

If some icons are missing, feel free to open a request or a PR.

1.3 Display a Collection

You can decide to include a collection in your homepage:

[params]
homeCollectionTitle = 'Posts'
homeCollection = 'posts'

The above example includes the /posts collection. Note that you can omit the title if you prefer.

2 Header

To pick pages to include in the header you must add the following elements:

[[params.menu]]
name = "home"
url = "/"

[[params.menu]]
name = "posts"
url = "/posts"

There exists an optional new tab parameter, to choose wether menu items are opened in a new tab or not.

[[params.menu]]
name = "posts"
url = "/posts"
newTab = true

3 Appearance

Typo has a built-in dark and light mode, you can decide the default one and control images on both modes.

3.1 Choosing a Theme

By default the mode in use is auto, if you want, you can hard-code a color scheme.

[params]
theme = 'auto | light | dark'

3.2 Choosing a Color Palette

Typo has the possibility to specify the color palette to use in the theme. The default one is black and white, but they can easily be added.

The color palettes are stored under assets/css/colors/* and the one in use can be specified with the following patameter:

[params]
colorPalette = 'default'

Note that omitting the parameter implies using the default palette.

This is the complete list of palettes available:

  • default;
  • catpuccin;
  • gruvebox;
  • eink.

More are to come.

3.3 Adding a Custom Color Palette

You can add a custom color palette by creating a new file under assets/css/colors/* named after your wanted palette name. Use another one as base and define the required parameters.

You can then use your new palette, by using its file name in the colorPalette site param.

3.4 Hide Header Mode

You can choose to hide the header on every page apart from the homepage with this parameter.

[params]
hideHeader = true

I strongly reccoment enabling breadcrumbs if you do so.

3.5 Note on Syntax Highlighting

Some color schemes seems to be broken using this theme, for instance, the default one, Monokai, is not well displayed, as pointed out in this issue. I suggest to try color schemes and see what can work for you.

[markup]
[markup.highlight]
style = 'algol'

3.6 Footer Customization

One can decide to hide the footer completely or to change it's content by specifiying the following parameters. Note that if you don't include the following parameters (or leave footerContent empty) the default footer is shown.

[params]
showFooter = true
footerContent = "Your **custom** md `footer`"

4 Controlling Images

4.1 Dark and Light Mode Images

Sometimes images don't look good in both light and dark mode. You can annotate the import path with a special tag to ensure an image is only shown on a specific color scheme.

![sstable](sstable-l.webp#light)
![sstable](sstable-d.webp#dark)

In the above example, the light image is a transparent background with dark lines, while the dark one has light ones.

If you omit the #dark or #light tags an image is always shown.

4.2 Images Sizing

There exist two tags to control sizing:

  • #small: the image takes 80% of the original scale.
  • #full: the image takes up all the available screen width.

You can also specify a caption using the following form:

![alt text](path.png#dark#small "Caption text")

I understand everyone could want a different scale for small images, you can override the default small class in your custom CSS:

.img-small img {
 scale: 80%;
}

Here you can find a blog post showing different tags combinations.

4.3 Adding new Image Tags

All tags are assumed to be related to an image class, which applies styling for the figure environment.

You can add a new one, provided you add a class named img-<tag_name>.

Feel free to have a look at existing ones to have a grasp on how they work.

5 Collections

Here are some parameters regarding collections, those apply to both the home displayed one and to the dedicated folder pages.

5.1 Pagination

Specify the maximum number of posts per page.

[params]
paginationSize = 100

5.2 Date Format

The date format can be tweaked with a format string.

[params]
listDateFormat = '2 Jan 2006'

5.3 Summary Toggle

Summaries can be turned on and off with this setting.

[params]
listSummaries = true

6 Single Page Parameters

The following parameters apply to single pages, they are meant to be inserted in the .md files introductions, apart from the date format.

6.1 Table of Contents

Show a table of contents at the beginning of the post.

toc: true

6.2 Sections Auto-numbering

Auto-number headings.

autonumber: true

Note that headings should start from level two.

6.3 Math Rendering

Enable math rendering.

math: true

6.4 Tags

Create tags associated with the post and decide to show them.

tags: ["database", "java"]
showTags: false

6.5 Display Read Time

Choose to display reading time.

readTime: true

6.6 Hide Back to Top

Choose to display back to top at the end of the page.

hideBackToTop: true

6.7 Hide Pagination Controls

Choose to display pagination controls at the end of the page.

hidePagination: true

6.8 Meta Description

You can speficy the post meta description as follows:

description: "Your Description"

6.9 Date Format

You can decide the date format to apply to single posts by setting the following param in the toml file:

[params]
singleDateFormat = '2 January 2006'

7 Other Parameters

Miscellaneous settings.

7.1 Home Meta Description

You can specify the homepage meta description with the following paramer:

[params]
description = "Your description"

7.2 Breadcrumbs

Show breadcrumbs on pages.

[params]
breadcrumbs = true

7.3 Comments

Enable comments on your posts using Giscus.

[params.giscus]
enable = false
repo = "your/repo"
repoid = "id"
category = "category"
categoryid = "categoryId"
mapping = "pathname"
theme = "preferred_color_scheme"

Tip: use preferred_color_scheme theme to have a consistent dark and light appearance.

7.4 Umami

You can include Umami in your website as follows:

[params.umami]
enable = true
websiteId = "unique-website-id"
jsLocation = "http://example.org/umami.js"

7.5 Favicons

The following favicons are included in the head of the website:

  • favicon.ico
  • favicon-16x16.png
  • favicon-32x32.png
  • android-chrome-192x192.png
  • apple-touch-icon.png

You must override the existing one in your static folder.

You can also specify a subdirectory of /static if you prefer using the following param:

[params]
faviconPath = 'your-path'

You can easily generate favicons using this website starting from your image. Here you can see an example of icons overriding default ones.

8 Custom CSS

The theme supports custom css, you can override anything you want by redefining classes in the assets/custom.css file.

For instance, changing the main widht can be done as follows:

:root {
    --main-width: 1024px; /* overrides default of 780px */
}

Note that backward incompatible changes in the CSS will likely not happen, but there might be cases in the future where backward compatibility is not possible. If you are overriding a huge amount of CSS I suggest you forking the project instead of defining it here.

9 Misc

Mermaid diagrams are supported by theme, just follow this reference to use them.

Clone this wiki locally