Add wiki source

tomfran · Jan 1, 2025 · 2adf635 · 2adf635
1 parent 159eef8
commit 2adf635
Show file tree

Hide file tree

Showing 12 changed files with 761 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -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
@@ -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>
diff --git a/wiki/features/appearance.md 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
@@ -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
@@ -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
@@ -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
@@ -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
+```