Merge pull request 'feat/update-documentation' (#11) from feat/update-documentation into main

Reviewed-on: stiebke/hugo-internet-weblog#11
This commit is contained in:
Stephan Hadan 2025-01-29 00:14:23 +01:00
commit 89895da447
2 changed files with 18 additions and 17 deletions

View file

@ -1,6 +1,7 @@
The MIT License (MIT)
Copyright (c) 2016 Josh Johnson
Enhancements: Copyright (c) 2025 Stephan Hadan
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in

View file

@ -4,7 +4,7 @@
The theme features a customizable bio-section and flickr-based photo stream in it's footer, unique layouts for displaying all posts sorted by year, and support for partials to customize style and javascript loaded.
To see more, [check out my blog which is rendered with this theme](http://jnjosh.com) and see it's [configuration on Github](https://github.com/jnjosh/jnjosh.com).
To see more, [check out my blog which is rendered with this theme](https://reaktionsfaehig.net) and see it's [configuration on my Forgejo instance](https://git.hadan-it.com/web/reaktionsfaehig.net).
![internet-weblog showing a Micropost.](https://git.hadan-it.com/stiebke/hugo-internet-weblog/raw/branch/main/images/screenshot.png)
@ -32,14 +32,13 @@ To see more, [check out my blog which is rendered with this theme](http://jnjosh
Inside the folder of your Hugo site run:
$ mkdir themes
$ cd themes
$ git clone https://github.com/jnjosh/internet-weblog.git
$ git submodule add https://git.hadan-it.com/web/reaktionsfaehig.net.git themes/internet-weblog
For more information read the official [setup guide](//gohugo.io/overview/installing/) for Hugo.
For more information read the official [setup guide](https://gohugo.io/installation/) for Hugo.
## Getting Started
There are a few concepts this theme employs to make a personal blog. It's important to read this as you may not see what you expect upon launching. Since this theme is built to be a personal blog it opts for some simplifications like using the ["Section Menu for the Lazy Blogger"](https://gohugo.io/extras/menus/#section-menu-for-the-lazy-blogger) option in Hugo for displaying a simple menu. It assumes you want to call your blog posts `posts` and organizes them as such. For example, creating a new post (or micropost, or photopost) with Hugo would require you typing:
There are a few concepts this theme employs to make a personal blog. It's important to read this as you may not see what you expect upon launching. Since this theme is built to be a personal blog it opts for some simplifications like using the ["Section Menu for the Lazy Blogger"](https://gohugo.io/content-management/menus/#section-menu-for-the-lazy-blogger) option in Hugo for displaying a simple menu. It assumes you want to call your blog posts `posts` and organizes them as such. For example, creating a new post (or micropost, or photopost) with Hugo would require you typing:
```
$ hugo new posts/my-new-post.md
@ -63,7 +62,7 @@ The theme works with other content types, but posts work best when grouped under
#### How to configure the menu in the blog's navigation
As mentioned above, this theme takes a simplistic approach to menus. In fact, it doesn't really support custom menus opting to just use Hugo's `main` menu. Because it uses the ["Section Menu for the Lazy Blogger"](https://gohugo.io/extras/menus/#section-menu-for-the-lazy-blogger) you'll need to make one change to your `config.toml` file. Add **main** as the `SectionPagesMenu`.
As mentioned above, this theme takes a simplistic approach to menus. In fact, it doesn't really support custom menus opting to just use Hugo's `main` menu. Because it uses the ["Section Menu for the Lazy Blogger"](https://gohugo.io/content-management/menus/#section-menu-for-the-lazy-blogger) you'll need to make one change to your `hugo.toml` file. Add **main** as the `SectionPagesMenu`.
```
SectionPagesMenu = "main"
@ -71,14 +70,14 @@ SectionPagesMenu = "main"
Because of this, your individual posts don't need to organize themselves into menu groupings. Everything is assumed to be grouped at the top level. One exception to this is if you want to add a custom page to the root of the menu. In this case you would want to add `menu: main` to your page's Front Matter.
You can control which menu items get an RSS icon and link by adding the `RSSSections` list to your Params section of your `config.toml`:
You can control which menu items get an RSS icon and link by adding the `RSSSections` list to your Params section of your `hugo.toml`:
```
[params]
RSSSections = [ "Posts", "Microposts", "Photos" ]
```
You can then control the name and weight of these menus in your `config.toml` by adding a section for each menu item you'd like to display:
You can then control the name and weight of these menus in your `hugo.toml` by adding a section for each menu item you'd like to display:
```
[[menu.main]]
@ -88,16 +87,16 @@ You can then control the name and weight of these menus in your `config.toml` by
url = "/posts/"
```
If you aren't sure of how this should look, see how [jnjosh.com uses this in it's config.toml](https://github.com/jnjosh/jnjosh.com/blob/main/config.toml).
If you aren't sure of how this should look, see how [reaktionsfaehig.net uses this in it's hugo.toml](https://git.hadan-it.com/web/reaktionsfaehig.net/src/branch/main/hugo.toml).
**Recommendation:** Add `SectionPagesMenu` to your `config.toml` file.
**Recommendation:** Add `SectionPagesMenu` to your `hugo.toml` file.
**Recommendation:** Don't set a `menu` in your post's Front Matter unless you want it to display on the navigation.
**Recommendation:** Customize the menus that get an RSS icon by adding the `RSSSections` parameter to your `config.toml` file.
**Recommendation:** Configure the menu items by adding `menu.main` sections to your `config.toml` file.
**Recommendation:** Customize the menus that get an RSS icon by adding the `RSSSections` parameter to your `hugo.toml` file.
**Recommendation:** Configure the menu items by adding `menu.main` sections to your `hugo.toml` file.
#### Defining yourself as the Author
It looks like most themes use the `author` variable to add something simple like your name. This theme uses more structured data about you and requires an `[params.author]` section. The details of what is affected by each property is defined below in the variables section, but you should add this section to your `config.toml`:
It looks like most themes use the `author` variable to add something simple like your name. This theme uses more structured data about you and requires an `[params.author]` section. The details of what is affected by each property is defined below in the variables section, but you should add this section to your `hugo.toml`:
```
[params.author]
@ -109,7 +108,7 @@ It looks like most themes use the `author` variable to add something simple like
FlickrID = "<Your Flickr ID>"
```
**Recommendation:** Don't use the `author` variable, use the above `[params.author]` section in your `config.toml`.
**Recommendation:** Don't use the `author` variable, use the above `[params.author]` section in your `hugo.toml`.
#### Customizing the Bio Section, 404 page, javascript, or stylesheets
@ -141,7 +140,7 @@ feature: "assets/posts/20240219/image.jpg"
#### Preferred Dark Appearance
If you want to enable a dark appearance, there is limited support for that. Currently, setting the `EnablePreferredDarkAppearance` param to true in your config.toml file will enable it in an automatic state—if the system is using dark mode.
If you want to enable a dark appearance, there is limited support for that. Currently, setting the `EnablePreferredDarkAppearance` param to true in your `hugo.toml` file will enable it in an automatic state—if the system is using dark mode.
### Variables
@ -165,7 +164,7 @@ If you want to enable a dark appearance, there is limited support for that. Curr
| `[params]` - `YearlyMicroposts` | `true` or `false` | No. If true, Microposts will have a page with a yearly grouping just like the posts. If not present or false, the default of not having a micropost yearly grouping is applied. |
| `[params]` - `SummarizeMicroposts` | `true` or `false` | No. If true, Microposts will be summarized in the main list just like posts with a continue reading link. If not present or false, the default of not summarizing microposts is applied. |
Here is an example `config.toml`:
Here is an example `hugo.toml`:
```
baseurl = "http://mysite.com/"
@ -240,13 +239,14 @@ This theme makes use of the following 3rd Party Libraries.
## License
This theme is released under MIT. For more information, please see the [License](http://jnjosh.mit-license.org).
This theme is released under MIT. For more information, please see the [License](https://git.hadan-it.com/stiebke/hugo-internet-weblog/src/branch/main/LICENSE.md).
## Contact
This is the first theme I've made for Hugo, so I'm sure I've done some things wrong or assumed too much. If you have ideas or things that should be fixed, please let me know.
- [Josh Johnson](http://jnjosh.com) [@jnjosh](https://mastodon.social/@jnjosh)
- Enhancements: [Stephan Hadan](https://stephan.hadan.de) [@stiebke](https://freiburg.social/@stiebke)
---