Are there any refenrece guide to update to version 4 of the theme

[SrNetoChan]

Question

Is there a guide or some references on how to move to v4 version. currently updating the submodule will break the site with several errors and warnings. I believe my docs and configurations may need to be changed to acomodate the changes.

[hossainemruz]

Hi @SrNetoChan! Thank you for bringing this up. Currently, there is no guide for upgrading from v3 to v4. I will try to write one as soon as possible.

[SrNetoChan]

Let me know if I can help somehow. Comparing the demo site older version with the new one might help understand what changes need to be done, right?

[hossainemruz]

This should be easy few steps:

1. Delete the submodule
2. Update the config.yaml file to be similar to this.
3. Follow the quickstart guide to run updated theme.

You shouldn't require any change in data and content folders.

[SrNetoChan]

In that case, I will try make it work and write down the process, in case you want to use it for docs

[hossainemruz]

That would be great! Thank you.

[SrNetoChan]

So, I have successefuly updated my site following your instruction. This are the note I took for doing it

Migration from V3 to v4.0 Toha Theme

1 - Remove toha theme submodule

The theme no longer uses a git submodule to be installed, therefore, we start by removing the toha theme submodule

git rm themes/toha/ git commit -m "Remove v3 theme"

2. Meet the requirements

For building the site locally we will need to update/install the following requirements:

Hugo version v0.118.x (extended) or later.
Go language version v1.18.x or later.
Node version v18.x and npm version 8.x or later.

3. Add missing files

The new theme needs a couple of new files

From the https://github.com/hugo-toha/hugo-toha.github.io sample site I have copied the following files

• LICENSE - (optional) This changes the license from GNU to MIT
• go.mod
• go.sum

Edited the go.mod file and changed the first line to point to your site repository

module github.com/<your username>/<my site repo name>

4. Update the config.yaml file

There were some changes in the way the config.yaml file needs to be written.

First, we need to replace the theme option by the module option, so remove this line

theme: "toha"

And add the following lines

# Use Hugo modules to add theme
module:
  imports:
  - path: github.com/hugo-toha/toha/v4
  mounts:
  - source: static/files
    target: static/files
  - source: ./node_modules/flag-icon-css/flags
    target: static/flags
  - source: ./node_modules/@fontsource/mulish/files
    target: static/files
  - source: ./node_modules/katex/dist/fonts
    target: static/fonts

Update the darkMode options, which is now under features. Remove this lines

 darkMode:
    provider: darkreader
    enable: true
    default: system

And add this under features: :

  features:

    # Enable dark theme
    darkMode:
      enable: true

A few sections we missing an extra option called services. the changes were in comment, analytics and support:

Comment

    comment:
      enable: false
      services:
        disqus:
...

Analytics

# Enable Analytics
analytics:
  enabled: true
 services:

...

Support

   # Enable Support
    support:
      enable: true
     services:
...

Some other options have changed 

`enableTOC: true` was replaced by

toc: enable: true

`enableTags: true` was replaced by

tags: enable: true on_card: true # enables tags in post cards

`showFlags: true` as replaced by

flags: enable: true

If you want to use different country flag for a language, specify them here.

  # flagOverwrites:
  #   - languageCode: en
  #     countryCode: us

## 5. Built the site

Building the site now requires a few more steps. At least for the first time you do it.

1. Load Hugo modules

hugo mod tidy

2. Install node modules

hugo mod npm pack npm install `

(This last command a few more files that I also added to the repo for caution. Not sure it needed or not.)

package-lock.json package.hugo.json package.json

I did not commit the /node_modules folder and actually added it to the .gitignore file

3. Build the site

hugo server -w

Update github workflows

My site was using a github workflow/action to deploy the site on each commit. I add to replace it by the one provided in the https://github.com/hugo-toha/hugo-toha.github.io, the merge/to/main.yml, because it deals with the loading of hugo modules and install node modules.

[eishundo]

Thanks @SrNetoChan. I had gone through the upgrade myself before I saw your notes. I had missed the "services" changes so glad I read through your guide.

Regarding:

analytics:
  enabled: true

I have changed my config to:

analytics:
  enable: true

The template works with both, but most of the other items appear to use "enable" rather than "enabled", so I updated for consistency.

Also see https://github.com/hugo-toha/toha/issues/856 if you are using a newer version of Hugo with GoogleAnalytics.

Question: What have you done with "assets/jsconfig.json"? I see this is in the repository for the example site (https://github.com/hugo-toha/hugo-toha.github.io/blob/main/assets/jsconfig.json), but can/should we add this to .gitignore?

[hossainemruz]

Question: What have you done with "assets/jsconfig.json"? I see this is in the repository for the example site (https://github.com/hugo-toha/hugo-toha.github.io/blob/main/assets/jsconfig.json), but can/should we add this to .gitignore?

I think it gets added automatically by the build process. You should be able to ignore that.