Add wiki source

9 files changed, 479 insertions, 0 deletions

diff --git a/wiki/features/appearance.md b/wiki/features/appearance.md
new file mode 100644
index 0000000..5d28cac
--- /dev/null
+++ b/wiki/features/appearance.md
@@ -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`"
+```
diff --git a/wiki/features/collections.md b/wiki/features/collections.md
new file mode 100644
index 0000000..afc6394
--- /dev/null
+++ b/wiki/features/collections.md
@@ -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
+```
diff --git a/wiki/features/controlling-images.md b/wiki/features/controlling-images.md
new file mode 100644
index 0000000..8f05df1
--- /dev/null
+++ b/wiki/features/controlling-images.md
@@ -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.
diff --git a/wiki/features/custom-css.md b/wiki/features/custom-css.md
new file mode 100644
index 0000000..0ca4411
--- /dev/null
+++ b/wiki/features/custom-css.md
@@ -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.
+
diff --git a/wiki/features/header.md b/wiki/features/header.md
new file mode 100644
index 0000000..9338f45
--- /dev/null
+++ b/wiki/features/header.md
@@ -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
+```
diff --git a/wiki/features/homepage.md b/wiki/features/homepage.md
new file mode 100644
index 0000000..45ff1b9
--- /dev/null
+++ b/wiki/features/homepage.md
@@ -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.
diff --git a/wiki/features/misc.md b/wiki/features/misc.md
new file mode 100644
index 0000000..149ff2c
--- /dev/null
+++ b/wiki/features/misc.md
@@ -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.
\ No newline at end of file
diff --git a/wiki/features/other-parameters.md b/wiki/features/other-parameters.md
new file mode 100644
index 0000000..7950598
--- /dev/null
+++ b/wiki/features/other-parameters.md
@@ -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.
diff --git a/wiki/features/single-page-parameters.md b/wiki/features/single-page-parameters.md
new file mode 100644
index 0000000..4b7949d
--- /dev/null
+++ b/wiki/features/single-page-parameters.md
@@ -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'
+```