mirrors/hugo-typo
1
0
Fork 0
mirror of https://github.com/tomfran/typo.git synced 2025-04-25 21:19:55 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add wiki source

Browse source
This commit is contained in:
Francesco 2025-01-01 18:03:30 +01:00
parent 159eef8f49
commit 2adf635926
12 changed files with 761 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

2
README.md
View file

@ -52,8 +52,6 @@ If you use the theme or found it useful you can support me by leaving a star ⭐
Contributions are always welcome, feel free to open issues and PRs with fixes or new features.
Also make sure to update the [Wiki](https://github.com/tomfran/typo-wiki) when introducing a new feature.
## 5 Typo Users
If you're using Typo for your website, feel free to add your website to [the list](https://github.com/tomfran/typo/blob/main/USERS.md) alongside what you do! 😊

119
wiki/contributors.md Normal file
View file

@ -0,0 +1,119 @@
---
title: "Contributors"
date: "2024-12-25"
summary: "List of Typo's contributors"
description: "List of Typo's contributors"
toc: false
readTime: false
autonumber: false
math: false
showTags: false
hidePagination: true
hideBackToTop: false
---
Here is a list of the 17 contributors and their contribution count for the theme:
<ul style="list-style-type: none; padding: 0; margin-top: 2rem">
<li style="margin-left: 0px; margin-bottom: .5rem;">
<span style="display: flex; align-items: bottom;">
<img src="https://avatars.githubusercontent.com/u/18344761?v=4" alt="tomfran" width="30" height="30" style="margin-right: 10px; border-radius: 50%;">
<a href="https://github.com/tomfran">tomfran</a>&nbsp;- 115
</span>
</li>
<li style="margin-left: 0px; margin-bottom: .5rem;">
<span style="display: flex; align-items: bottom;">
<img src="https://avatars.githubusercontent.com/u/2759499?v=4" alt="runofthemillgeek" width="30" height="30" style="margin-right: 10px; border-radius: 50%;">
<a href="https://github.com/runofthemillgeek">runofthemillgeek</a>&nbsp;- 8
</span>
</li>
<li style="margin-left: 0px; margin-bottom: .5rem;">
<span style="display: flex; align-items: bottom;">
<img src="https://avatars.githubusercontent.com/u/61804369?v=4" alt="arunmathaisk" width="30" height="30" style="margin-right: 10px; border-radius: 50%;">
<a href="https://github.com/arunmathaisk">arunmathaisk</a>&nbsp;- 5
</span>
</li>
<li style="margin-left: 0px; margin-bottom: .5rem;">
<span style="display: flex; align-items: bottom;">
<img src="https://avatars.githubusercontent.com/u/14153526?v=4" alt="jpvg10" width="30" height="30" style="margin-right: 10px; border-radius: 50%;">
<a href="https://github.com/jpvg10">jpvg10</a>&nbsp;- 2
</span>
</li>
<li style="margin-left: 0px; margin-bottom: .5rem;">
<span style="display: flex; align-items: bottom;">
<img src="https://avatars.githubusercontent.com/u/85934?v=4" alt="vxnick" width="30" height="30" style="margin-right: 10px; border-radius: 50%;">
<a href="https://github.com/vxnick">vxnick</a>&nbsp;- 2
</span>
</li>
<li style="margin-left: 0px; margin-bottom: .5rem;">
<span style="display: flex; align-items: bottom;">
<img src="https://avatars.githubusercontent.com/u/30109443?v=4" alt="crnh" width="30" height="30" style="margin-right: 10px; border-radius: 50%;">
<a href="https://github.com/crnh">crnh</a>&nbsp;- 2
</span>
</li>
<li style="margin-left: 0px; margin-bottom: .5rem;">
<span style="display: flex; align-items: bottom;">
<img src="https://avatars.githubusercontent.com/u/91705618?v=4" alt="gigaArpit" width="30" height="30" style="margin-right: 10px; border-radius: 50%;">
<a href="https://github.com/gigaArpit">gigaArpit</a>&nbsp;- 1
</span>
</li>
<li style="margin-left: 0px; margin-bottom: .5rem;">
<span style="display: flex; align-items: bottom;">
<img src="https://avatars.githubusercontent.com/u/17879459?v=4" alt="Frankkkkk" width="30" height="30" style="margin-right: 10px; border-radius: 50%;">
<a href="https://github.com/Frankkkkk">Frankkkkk</a>&nbsp;- 1
</span>
</li>
<li style="margin-left: 0px; margin-bottom: .5rem;">
<span style="display: flex; align-items: bottom;">
<img src="https://avatars.githubusercontent.com/u/55957?v=4" alt="jder" width="30" height="30" style="margin-right: 10px; border-radius: 50%;">
<a href="https://github.com/jder">jder</a>&nbsp;- 1
</span>
</li>
<li style="margin-left: 0px; margin-bottom: .5rem;">
<span style="display: flex; align-items: bottom;">
<img src="https://avatars.githubusercontent.com/u/22883661?v=4" alt="mesmur" width="30" height="30" style="margin-right: 10px; border-radius: 50%;">
<a href="https://github.com/mesmur">mesmur</a>&nbsp;- 1
</span>
</li>
<li style="margin-left: 0px; margin-bottom: .5rem;">
<span style="display: flex; align-items: bottom;">
<img src="https://avatars.githubusercontent.com/u/39889850?v=4" alt="jkfujr" width="30" height="30" style="margin-right: 10px; border-radius: 50%;">
<a href="https://github.com/jkfujr">jkfujr</a>&nbsp;- 1
</span>
</li>
<li style="margin-left: 0px; margin-bottom: .5rem;">
<span style="display: flex; align-items: bottom;">
<img src="https://avatars.githubusercontent.com/u/12296574?v=4" alt="baragoon" width="30" height="30" style="margin-right: 10px; border-radius: 50%;">
<a href="https://github.com/baragoon">baragoon</a>&nbsp;- 1
</span>
</li>
<li style="margin-left: 0px; margin-bottom: .5rem;">
<span style="display: flex; align-items: bottom;">
<img src="https://avatars.githubusercontent.com/u/42381601?v=4" alt="khalidzohaib" width="30" height="30" style="margin-right: 10px; border-radius: 50%;">
<a href="https://github.com/khalidzohaib">khalidzohaib</a>&nbsp;- 1
</span>
</li>
<li style="margin-left: 0px; margin-bottom: .5rem;">
<span style="display: flex; align-items: bottom;">
<img src="https://avatars.githubusercontent.com/u/13006869?v=4" alt="francoposa" width="30" height="30" style="margin-right: 10px; border-radius: 50%;">
<a href="https://github.com/francoposa">francoposa</a>&nbsp;- 1
</span>
</li>
<li style="margin-left: 0px; margin-bottom: .5rem;">
<span style="display: flex; align-items: bottom;">
<img src="https://avatars.githubusercontent.com/u/15337300?v=4" alt="nyms7" width="30" height="30" style="margin-right: 10px; border-radius: 50%;">
<a href="https://github.com/nyms7">nyms7</a>&nbsp;- 1
</span>
</li>
<li style="margin-left: 0px; margin-bottom: .5rem;">
<span style="display: flex; align-items: bottom;">
<img src="https://avatars.githubusercontent.com/u/68630827?v=4" alt="simon-siggaard" width="30" height="30" style="margin-right: 10px; border-radius: 50%;">
<a href="https://github.com/simon-siggaard">simon-siggaard</a>&nbsp;- 1
</span>
</li>
<li style="margin-left: 0px; margin-bottom: .5rem;">
<span style="display: flex; align-items: bottom;">
<img src="https://avatars.githubusercontent.com/u/95117608?v=4" alt="smdp26" width="30" height="30" style="margin-right: 10px; border-radius: 50%;">
<a href="https://github.com/smdp26">smdp26</a>&nbsp;- 1
</span>
</li>
</ul>

85
wiki/features/appearance.md Normal file
View file

@ -0,0 +1,85 @@
---
title: "Appearance"
date: "2024-10-12"
summary: "Appearance parameters"
description: "Appearance parameters"
toc: false
readTime: false
autonumber: true
math: false
showTags: false
---
Typo has a built-in dark and light mode, you can decide the default one and control images on both modes.
## Choosing a Theme
By default the mode in use is auto, if you want, you can hard-code a color scheme.
```toml
[params]
theme = 'auto | light | dark'
```
## 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:
```toml
[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.
## 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.
## Hide Header Mode
You can choose to hide the header on every page apart from the homepage with this parameter.
```toml
[params]
hideHeader = true
```
I strongly reccoment enabling [breadcrumbs](#72-breadcrumbs) if you do so.
## 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](https://github.com/tomfran/typo/issues/17).
I suggest to try [color schemes](https://xyproto.github.io/splash/docs/all.html) and see what can work for you.
```toml
[markup]
[markup.highlight]
style = 'algol'
```
## 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.
```toml
[params]
showFooter = true
footerContent = "Your **custom** md `footer`"
```

40
wiki/features/collections.md Normal file
View file

@ -0,0 +1,40 @@
---
title: "Collections"
date: "2024-10-10"
summary: "Collections parameters"
description: "Collections parameters"
toc: false
readTime: false
autonumber: true
math: false
showTags: false
---
Here are some parameters regarding collections, those apply to both the home displayed one and to the dedicated folder pages.
## Pagination
Specify the maximum number of posts per page.
```toml
[params]
paginationSize = 100
```
## Date Format
The date format can be tweaked with a format string.
```toml
[params]
listDateFormat = '2 Jan 2006'
```
## Summary Toggle
Summaries can be turned on and off with this setting.
```toml
[params]
listSummaries = true
```

54
wiki/features/controlling-images.md Normal file
View file

@ -0,0 +1,54 @@
---
title: "Controlling Images"
date: "2024-10-11"
summary: "Controlling Images parameters"
description: "Controlling Images parameters"
toc: false
readTime: false
autonumber: true
math: false
showTags: false
---
## 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.
```md
![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.
## 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:
```css
.img-small img {
scale: 80%;
}
```
[Here](https://tomfran.github.io/posts/hugo-images/) you can find a blog post showing different tags combinations.
## 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.

27
wiki/features/custom-css.md Normal file
View file

@ -0,0 +1,27 @@
---
title: "Custom CSS"
date: "2024-10-07"
summary: "Custom CSS parameters"
description: "Custom CSS parameters"
toc: false
readTime: false
autonumber: true
math: false
showTags: false
hideBackToTop: true
---
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:
```css
: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.

32
wiki/features/header.md Normal file
View file

@ -0,0 +1,32 @@
---
title: "Header"
date: "2024-10-13"
summary: "Header parameters"
description: "Header parameters"
toc: false
readTime: false
autonumber: true
math: false
showTags: false
---
To pick pages to include in the header you must add the following elements:
```toml
[[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.
```toml
[[params.menu]]
name = "posts"
url = "/posts"
newTab = true
```

56
wiki/features/homepage.md Normal file
View file

@ -0,0 +1,56 @@
---
title: "Homepage"
date: "2024-10-14"
summary: "Homepage parameters"
description: "Homepage parameters"
toc: false
readTime: false
autonumber: true
math: false
showTags: false
---
The homepage offers minimal customization options, you can specify an intro, a collection to display, and social icons.
## 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.
```toml
[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.
## Social Icons
You can include social icons after the intro like follows.
```toml
[[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.
## Display a Collection
You can decide to include a collection in your homepage:
```toml
[params]
homeCollectionTitle = 'Posts'
homeCollection = 'posts'
```
The above example includes the `/posts` collection. Note that you can omit the title if you prefer.

14
wiki/features/misc.md Normal file
View file

@ -0,0 +1,14 @@
---
title: "Misc"
date: "2024-10-06"
summary: "Misc parameters"
description: "Misc parameters"
toc: false
readTime: false
autonumber: true
math: false
showTags: false
hideBackToTop: true
---
Mermaid diagrams are supported by theme, just follow [this reference](https://gohugo.io/content-management/diagrams/#mermaid-diagrams) to use them.

82
wiki/features/other-parameters.md Normal file
View file

@ -0,0 +1,82 @@
---
title: "Other Parameters"
date: "2024-10-08"
summary: "Other Parameters parameters"
description: "Other Parameters parameters"
toc: false
readTime: false
autonumber: true
math: false
showTags: false
---
Miscellaneous settings.
## Home Meta Description
You can specify the homepage meta description with the following paramer:
```toml
[params]
description = "Your description"
```
## Breadcrumbs
Show breadcrumbs on pages.
```toml
[params]
breadcrumbs = true
```
## Comments
Enable comments on your posts using [Giscus](https://giscus.app/).
```toml
[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.
## Umami
You can include [Umami](https://umami.is/) in your website as follows:
```toml
[params.umami]
enable = true
websiteId = "unique-website-id"
jsLocation = "http://example.org/umami.js"
```
## Favicons
The following favicons are included in the head of the website:
- `favicon.ico`
- `favicon-16xng`
- `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:
```toml
[params]
faviconPath = 'your-path'
```
You can easily generate favicons using [this website](https://realfavicongenerator.net/) starting from your image.
[Here](https://github.com/tomfran/tomfran.github.io/tree/main/static) you can see an example of icons overriding default ones.

89
wiki/features/single-page-parameters.md Normal file
View file

@ -0,0 +1,89 @@
---
title: "Single Page Parameters"
date: "2024-10-09"
summary: "Single Page Parameters parameters"
description: "Single Page Parameters parameters"
toc: false
readTime: false
autonumber: true
math: false
showTags: false
---
The following parameters apply to single pages, they are meant to be inserted in the `.md` files introductions, apart from the date format.
## Table of Contents
Show a table of contents at the beginning of the post.
```md
toc: true
```
## Sections Auto-numbering
Auto-number headings.
```md
autonumber: true
```
Note that headings should start from level two.
## Math Rendering
Enable math rendering.
```md
math: true
```
## Tags
Create tags associated with the post and decide to show them.
```md
tags: ["database", "java"]
showTags: false
```
## Display Read Time
Choose to display reading time.
```md
readTime: true
```
## Hide Back to Top
Choose to display back to top at the end of the page.
```md
hideBackToTop: true
```
## Hide Pagination Controls
Choose to display pagination controls at the end of the page.
```md
hidePagination: true
```
## Meta Description
You can speficy the post meta description as follows:
```md
description: "Your Description"
```
## Date Format
You can decide the date format to apply to single posts by setting the following param in the toml file:
```toml
[params]
singleDateFormat = '2 January 2006'
```

163
wiki/setup.md Normal file
View file

@ -0,0 +1,163 @@
---
title: "Setup"
date: "2024-10-12"
summary: "How to setup a Hugo's website using Typo as a theme."
description: "Getting started with Typo theme"
toc: false
readTime: false
autonumber: true
math: false
showTags: false
hidePagination: true
---
## Installation
Below are the ways to get started with the Typo theme.
### Getting Started
First of all, create a new Hugo project as follows:
```bash
hugo new site <your site name> --config toml
```
### Downloading the Theme
Themes are contained in the `/themes` directory, there are different ways to get Typo there
**Submodule - Recommended**
```bash
git submodule add --depth=1 https://github.com/tomfran/typo.git themes/typo
git submodule update --init --recursive
```
**Cloning**
```bash
git clone https://github.com/tomfran/typo themes/typo --depth=1
```
You need to keep it updated manually by pulling.
**Manual download a release**
Finally, you can manually download a [release](https://github.com/tomfran/typo/releases) and unzip it into the appropriate folder.
## Sample Config
Use those to get started with the theme. You can find a complete overview of the available features [here](https://tomfran.github.io/typo-wiki/features/).
[Here](https://github.com/tomfran/tomfran.github.io) you can find a repo using this theme.
### Site Config
Here is a sample `hugo.toml` config to get started with the theme.
```toml
baseURL = 'https://example.org/'
languageCode = 'en-us'
title = 'My website'
theme = 'typo'
[taxonomies]
tag = 'tags'
# Google analytics code
googleAnalytics = "G-xxxxxxxxx"
[params]
# Meta description
description = "A Tech Blog"
# Appearance settings
theme = 'auto'
colorPalette = 'default'
hideHeader = false
# Intro on main page, content is markdown
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.
"""
# Collection to display on home
homeCollectionTitle = 'Posts'
homeCollection = 'posts'
# Lists parameters
paginationSize = 100
listSummaries = true
listDateFormat = '2 Jan 2006'
# Breadcrumbs
breadcrumbs = true
# Social icons
[[params.social]]
name = "linkedin"
url = "https://www.linkedin.com/in/user/"
[[params.social]]
name = "medium"
url = "https://medium.com/@user"
[[params.social]]
name = "github"
url = "https://github.com/user"
# Main menu pages
[[params.menu]]
name = "home"
url = "/"
[[params.menu]]
name = "posts"
url = "/posts"
[[params.menu]]
name = "about"
url = "/about"
# Syntax highligth on code blocks
[markup]
[markup.highlight]
style = 'algol'
# Giscus comments
[params.giscus]
enable = false
repo = "user/repo"
repoid = "repoId"
category = "General"
categoryid = "categoryId"
mapping = "pathname"
theme = "preferred_color_scheme"
```
### Post Config
Sample post config.
```markdown
---
title: "Log-Structured Merge Tree"
date: "2023-11-12"
summary: "An LSM Tree overview and Java implementation."
description: "An LSM Tree overview and Java implementation."
toc: true
readTime: true
autonumber: true
math: true
tags: ["database", "java"]
showTags: false
hideBackToTop: false
---
```
## Support
If you use the theme or found it useful you can support me by leaving a star :star: to Typo's Github repository or opening issues and PRs with fixes or new features.