Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update site configuration guide to work with v4 version #245

Merged
merged 1 commit into from
Jan 5, 2024
Merged

Update site configuration guide to work with v4 version #245

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 26 additions & 58 deletions content/posts/configuration/site-parameters/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,25 +8,24 @@ menu:
parent: configuration
weight: 105
---
{{< alert type="danger" >}}
This doc is outdated. For up-to-date examples, please follow this sample [repo](https://github.com/hugo-toha/hugo-toha.github.io).
{{< /alert >}}

After installing this theme, when you first run your site, it will start with the default parameters. It should look similar to this example site except it will not have any sections on the homepage. Those sections are added via some data files. In the next few posts, I am going to show you how you can add those sections by providing the data files.
After installing this theme, when you first run your site, it will start with the default parameters. It should look similar to this example site, but it won't have any sections on the homepage. Don't worry, you can easily add those sections by providing the necessary data files.

In this post, I am going to show you how you can change the site parameters to change background, logo, author information, and enable/disable various features.
In the upcoming posts, I'll guide you on how to add those sections and customize your site. But first, let's start with changing the site parameters. You can modify the background, logo, author information, and enable/disable various features.

For a comprehensive list of available configuration parameters, please refer to the [example site](https://github.com/hugo-toha/hugo-toha.github.io/tree/main).

### Add Background Image

At first, let's set a background on your website. Put your desired background image in the `assets/images` directory. Then add the following in the `params` section of your `config.yaml` file.

```yaml
background: "images/<your background image name(with file extension)>"
background: "images/name-of-your-background-image.jpg"
```

### Add Site's Logo

Now, let's add a logo for your site. You have to provide two different logos. One is for the transparent navbar and another for the non-transparent navbar. Put your logos into `assets/images` directory and add the following in the `params` section of `config.yaml` file.
To add logos for your site, you need two different logos: one for the transparent navbar and another for the non-transparent navbar. Place your logos in the `assets/images` directory and add the following code under the `params` section of your `config.yaml` file.

```yaml
# The inverted logo will be used in the initial transparent navbar and
Expand All @@ -39,18 +38,21 @@ logo:

### Enable Blog Post

If you want to write some blog posts on your site, you have to enable it first. Let's enable blog posting by adding the following in the `params` section of your `config.yaml` file.
To enable blog posting on your site, you need to make some changes in the `config.yaml` file. Locate the `params.features` section and add the following code:

```yaml
enableBlogPost: true
# Enable and configure blog posts
blog:
enable: true
```

### Enable `Table Of Contents`

Now, if you want to show `Table Of Contents` section in your blog post, you have to enable it in the `params` section of `config.yaml` file.
Now, if you want to show `Table Of Contents` section in your blog post, you have to enable it in the `params.features` section of `config.yaml` file.

```yaml
enableTOC: true
toc:
enable: true
```

You can also control the level of your TOC by adding the following configuration in the `markup` section of your `config.yaml` file.
Expand All @@ -67,24 +69,23 @@ Here, we have configured our TOC to show all headings from `h2` to `h6`.

### Enable `<Improve This Page>` Button

If you want to provide the readers an easy way to improve a post (i.e. typo fix, indentation fix, etc.), you can enable `<Improve This Page>` button by adding your git repository URL in the `params` section of your `config.yaml` file.
If you want to allow readers to easily improve a post by making corrections such as fixing typos or indentation, you can enable the `<Improve This Page>` button. To do this, add your git repository URL in the `params` section of your `config.yaml` file.

```yaml
gitRepo: <your site's Github repo URL>
```

This will add a button labeled `Improve This Page` at the bottom of every blog post. The button will route the user directly to the respective edit page in Github.

If your default branch isn't called `main` then you need to add your git default branch in the `params` section of your `config.yaml` file.
If your default branch is not named `main`, you need to specify your git default branch in the `params` section of your `config.yaml` file.

```yaml
gitBranch: <your git default branch name>
```

### Enable/Disable Newsletter
### Enable Newsletter

The newsletter feature only supports Mailchimp for now.
Add the following in the `params` section of `config.yaml` file.
To enable the newsletter feature, you need to provide the necessary parameters under the `params.footer` section in your `config.yaml` file. Currently, the newsletter feature only supports the Mailchimp provider. Here is an example of how it should look:

```yaml
newsletter:
Expand All @@ -93,7 +94,7 @@ newsletter:
mailchimpURL: https://github.us1.list-manage.com/subscribe/post?u=19de52a4603135aae97163fd8&amp;id=094a24c76e
```

If you don't want to use the newsletter feature, you can hide it by adding following in the `params` section of `config.yaml` file.
To disable the newsletter feature, you can set the following configuration:

```yaml
newsletter:
Expand All @@ -102,7 +103,7 @@ newsletter:

### Enable RAW HTML in the Markdown File

If you want to use RAW HTML in your markdown files, you have to enable unsafe rendering. Otherwise, Hugo will not render the HTML. You can enable unsafe markdown rendering by adding following `goldmark` settings in the `markup` section of `config.yaml` file.
If you want to include RAW HTML in your markdown files, you need to enable unsafe rendering. Without enabling this, Hugo will not render the HTML. To enable unsafe markdown rendering, add the following `goldmark` settings to the `markup` section of your `config.yaml` file.

```yaml
markup:
Expand All @@ -113,7 +114,7 @@ markup:

### Add Author Information

Now, provide your basic information. Create a `author.yaml` file in your `/data` directory and add the author information there.
Now, provide your basic information. Create a `author.yaml` file in your `/data/en` directory and add the author information there.

```yaml
# some information about you
Expand All @@ -140,19 +141,19 @@ summary:
- I love to work with some fun projects
```

> Note: `contactInfo` paramerters will use the `icon` parameter to find the icon. This parameter must match the font awesome icon names [examples](https://fontawesome.com/search?o=r&f=brands)
> Note: The `contactInfo` parameters will use the `icon` field to find the respective icon. Make sure the `icon` field matches the font awesome icon names. You can find examples [here](https://fontawesome.com/search?o=r&f=brands).

### Add Copyright Notice

Let's add a copyright notice for your site. This will be shown at the bottom of the footer. Create `site.yaml` file in your `/data` directory and add the following section there.
To add a copyright notice for your site, create a `site.yaml` file in your `/data/en` directory. Add the following section to the file:

```yaml
copyright: © 2020 Copyright.
copyright: © 2024 Copyright.
```

### Site's Description

Now, add a description of your site that will help the search engines to find your site. Add a description section in your `site.yaml` file.
To add a description of your site that will help search engines find your site, you need to add a `description` section in your `site.yaml` file.

```yaml
# Meta description for your site. This will help the search engines to find your site.
Expand All @@ -161,7 +162,7 @@ description: Example site for hugo theme Toha.

### Add Custom Menus

If you want to add some custom menus in the navbar, you can easily add them by adding the following in the `site.yaml` file. Custom menus are visible in the navigation bar by default. To hide them, set `hideFromNavbar` to `true`. Custom menus are hidden from the footer's navigation area by default. To show a custom menu item in the footer, set its `showOnFooter` property to `true`.
To add custom menus in the navbar, you can modify the `site.yaml` file. By default, custom menus are visible in the navigation bar. To hide a custom menu, set the `hideFromNavbar` property to `true`. By default, custom menus are hidden from the footer's navigation area. To show a custom menu item in the footer, set its `showOnFooter` property to `true`. This is particularly helpful when you want to add a link to another site in the navbar.

```yaml
customMenus:
Expand All @@ -171,37 +172,4 @@ customMenus:
showOnFooter: true
```

This is particularly helpful when you want to add a link to another site in the navbar.

### Example `params` Section

Finally, here is the `params` section used in this example site.

```yaml
# Site parameters
params:
# background image of the landing page
background: "images/background.jpg"

# Provide logos for your site. The inverted logo will be used in the initial
# transparent navbar and the main logo will be used in the non-transparent navbar.
# It will default to the theme logos if not provided.
logo:
main: images/main-logo.png
inverted: images/inverted-logo.png
favicon: images/favicon.png

# GitHub repo URL of your site
gitRepo: https://github.com/hossainemruz/toha-example-site

# specify whether you want to write some blog posts or not
enableBlogPost: true

# specify whether you want to show Table of Contents in reading page
enableTOC: true

# Provide newsletter configuration. This feature hasn't been implemented yet.
# Currently, you can just hide it from the footer.
newsletter:
enable: true
```
Now, you can run your site and see the changes. In the upcoming posts, I'll guide you on how to add sections to your homepage and customize your site further.