diff options
author | Francesco <tomaselli.fr@gmail.com> | 2025-01-01 18:03:30 +0100 |
---|---|---|
committer | Francesco <tomaselli.fr@gmail.com> | 2025-01-01 18:03:30 +0100 |
commit | eb82ffe7f2b92cab3bc632229c6f8bae70d33ff0 (patch) | |
tree | 4c07acd900c6f84cc1377503dadbb27d9184564c | |
parent | b6554e22005f1c8460bb60e6894503e06f232551 (diff) |
Add wiki source
-rw-r--r-- | README.md | 2 | ||||
-rw-r--r-- | wiki/contributors.md | 119 | ||||
-rw-r--r-- | wiki/features/appearance.md | 85 | ||||
-rw-r--r-- | wiki/features/collections.md | 40 | ||||
-rw-r--r-- | wiki/features/controlling-images.md | 54 | ||||
-rw-r--r-- | wiki/features/custom-css.md | 27 | ||||
-rw-r--r-- | wiki/features/header.md | 32 | ||||
-rw-r--r-- | wiki/features/homepage.md | 56 | ||||
-rw-r--r-- | wiki/features/misc.md | 14 | ||||
-rw-r--r-- | wiki/features/other-parameters.md | 82 | ||||
-rw-r--r-- | wiki/features/single-page-parameters.md | 89 | ||||
-rw-r--r-- | wiki/setup.md | 163 |
12 files changed, 761 insertions, 2 deletions
@@ -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! 😊 diff --git a/wiki/contributors.md b/wiki/contributors.md new file mode 100644 index 0000000..31a476a --- /dev/null +++ b/wiki/contributors.md @@ -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> - 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> - 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> - 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> - 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> - 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> - 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> - 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> - 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> - 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> - 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> - 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> - 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> - 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> - 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> - 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> - 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> - 1 + </span> + </li> + </ul> 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 + + +``` + +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: + +``` + +``` + +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' +``` diff --git a/wiki/setup.md b/wiki/setup.md new file mode 100644 index 0000000..b5ddc79 --- /dev/null +++ b/wiki/setup.md @@ -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.
\ No newline at end of file |