Forem: JulieS

Hugo: How to Add a Table of Contents(TOC) to Your Post?

JulieS — Fri, 28 Apr 2023 12:45:00 +0000

Maybe you want to add a Table of Contents ( TOC ) to the articles on your Hugo site but don’t know how to do it, or maybe you want to insert a TOC somewhere in the middle of your post. This is the tutorial for you.

1. The TOC configuration

First you need to see if your Hugo theme contains Table of Contents ( TOC ) settings. Open the config.toml file in your Hugo site folder ( Later we’ll call it YourSite in this article ), find the parameter tableOfContents ( or toc ), set it to be true like this:

tableOfContents = true

Then, if your Hugo theme has a TOC configuration, a TOC will be added at the beginning of every post.

Q: What if I don’t want to show the TOC of an article?

A: Go to the front matter of that article, and set:

toc: false

Then only the TOC of that article won’t be shown.

2. How to insert a TOC in the middle of your post?

However, some Hugo themes don’t have Table of Contents ( TOC ) settings, or you may want to insert a TOC somewhere in the middle of the post. In that case, you can use Hugo shortcodes.

Hugo Shortcodes Page introduces shortcodes as this:

A shortcode is a simple snippet inside a content file that Hugo will render using a predefined template.

We can think of a shortcode as a function. When we call it, Hugo will render in the way the shortcode defined.

How to use shortcodes?

By written {{% shortcodeName parameters %}} or {{< shortcodeName parameters >}} wherever you want to use it in the markdown article. Actually, if you’ve read my first tutorial , you may have already used shortcodes. In it the shortcode figure is used to display an image and its title.

{{< figure src="/image1.jpg" title="image1_title" >}}

figure is a built-in shortcode. There is no built-in shortcode for Table of Contents ( TOC ) , so we need to define it, which is a bit hard for beginners. Thankfully the author of Hugo theme hugo-octopress has done it for us. You just need to download this repository on GitHub . Go to YourSite > layouts folder, create a shortcodes folder in it if it doesn’t exist. Then copy the toc.html from the downloaded Hugo-Shortcodes > shortcodes folder to YourSite > layouts > shortcodes folder.

To insert TOC somewhere in your article, just write a line: {{% toc %}} ( or {{< toc >}} ).

3. Set the range of headings to be displayed

Sometimes you may find the page doesn’t show all the headings, and you can fix it by setting in YourSite > config.toml:

[markup]
  [markup.tableOfContents]
    startLevel = 3
    endLevel = 5

The startLevel and endLevel refer to the highest and lowest levels of the headings to be shown. For example, the above setting means that the TOC only shows headings between level 3 and level 5.

References

Hugo Shortcodes Page
The author of the hugo-octopress theme introduced the use of shortcodes in detail and I find it helpful : https://github.com/parsiya/Hugo-Octopress/blob/master/README.md#shortcodes

Switching from Hexo to Hugo

JulieS — Thu, 27 Apr 2023 12:30:00 +0000

Several months ago I switched my site from Hexo-building to Hugo-building. Some readers asked me why the move and how to do it, so here I’d like to share my experience with you.

1. Hugo v.s. Hexo

Both Hexo and Hugo are static site generators, so why did I choose Hugo?

Hugo is super fast. At first I thought it means the page load time is short, so my readers could view the pages of my site instantly, and that’s the reason I decided to switch to Hugo. Later I realized it refers to the site building speed ( < 1ms per page according to Hugo site ), which means I can build the site fast and preview the changes in real time. It’s really a benefit, especially when you have written hundreds of articles, for you can still build your site in seconds (or even in a second) .

Besides, Hexo depends on Node.js. Sometimes when you install a wrong version of Node.js, it leads to problems. You don’t need to worry about that in Hugo because you don’t need to install external dependencies for it.

What about Hugo’s drawbacks?

From my experience, compared with Hexo, the site configuration of Hugo is a bit difficult for beginners. Hexo provides a default theme for you to begin with. While in Hugo, at first you have to pick a theme and install it. Besides, Hexo has a site configuration as well as a theme configuration. The site configuration fits all themes and saves your time when you change the theme. While Hugo has only one configuration file, and different themes have different settings, which makes beginners a little confused.

2. How I switched from Hexo to Hugo?

Since I have written some posts on the Hexo site, the main question is how to switch to Hugo without changing the links of the posts. I find this article helpful, so I followed the instructions in it to make the change.

2.1. Generate the pages by Hugo locally

First I followed the step0 and step1 in my first tutorial to build a Hugo site. Then:

(1) Copy the posts from MyHexoSite > source > _posts to MyHugoSite > content > post folder.

Please use copy , not move , so that if something went wrong, you can go to MyHexoSite folder and try it again. And I also advice you to make a backup of MyHexoSite folder.

(2) Change the front matter of the posts.

In Hexo the the published date is formatted as date:yyyy-mm-dd HH:MM:SS , while in Hugo a time zone needs to be added. For example, in my articles the format is date:yyyy-mm-ddTHH:MM:SS+08:00 .

(3) Change the image links ( You may read Step1.5 in my first tutorial first)

For local images:

Copy all images from MyHexoSite > source > _posts > imgs folder to MyHugoSite > static > imgs folder, then change the links in the markdown files.

If in Hexo the link is like:

![image1_title](imgs/image1.jpg)

In Hugo it’s changed to:

![image1_title](/imgs/image1.jpg)

If in Hexo the link is like:

<img src="imgs/image1.jpg" alt="image1_title" align=center />

Here align=center is optional. It’s set to display the image in the center of the line.

In Hugo it’s changed to:

{{< figure src="/imgs/image1.jpg" title="image1_title" >}}

For web images:

If in Hexo the link is like:

![image2_title](image2_weblink)

You can keep the links as the same.

If in Hexo the link is like:

<img src="image2_weblink" alt="image2_title" align=center />

You need to remove the double quotes around image2_weblink and image2_title.

(4) permanent link

To be consistent with the URL of my Hexo site, I set the permanent links in the config.toml of the Hugo site as:

[permalinks]
  post = "/:year/:month/:day/:filename/"

I used the Next theme of Hexo. You may need to refer to the links of your own Hexo site before setting the permalinks.

2.2. Push to GitHub for the first time

(1) Save the links of several articles of your Hexo site. Later you can use them to check the links of your Hugo site.

(2) Follow the step2 in my first tutorial, except one thing. Because I have pushed Hexo-generated pages to GitHub before, the GitHub repository was not empty, the first time I added -f after git push as follows:

git add .
git commit -m "YourCommitMessage"
git push -f upstream master

From the next time I use git push upstream master .

(3) Clicking the links saved in step(1) and check whether the links point to the same articles as before.

References

Comparison of Hexo and Hugo: https://www.stackshare.io/stackups/hexo-vs-hugo
Switch from Hexo to Hugo: https://jdhao.github.io/2018/10/10/hexo_to_hugo/

How to Build a Personal Website Using GitHub Pages and Hugo?

JulieS — Wed, 26 Apr 2023 12:16:52 +0000

A personal website is a good place to display your work, either your projects or your technical notes. Then how to build one? In this article I’ll introduce the simplest way to build a site. ( Maybe you’d like to have a look at my site first.)

Site-Building Pipeline

There are two kinds of sites: static sites and dynamic ones.

Static sites generate web pages locally, and put them on the server, so every user will get the same view when they click the link.
Dynamic sites display different pages to different users on their requests, so it need things like databases.

As beginners, we choose the simpler one — static sites, and it’s easy to follow after you learn the pipeline.

Figure 1. The pipeline of building a static website

As shown in the figure above, there are two main steps in building a static website:

Generate pages locally. The popular static site generators (or frameworks) are JekyII, Hugo, Hexo, etc. Here we’ll use Hugo as an example. Many people (including me) like Hugo because it’s super fast to build a site.
Deploy the site to the server. Here we’ll use GitHub as the server to store the pages.

Not that hard, right ? Now let’s dive into the details.

Step 0 : Preparation

Install Git . We will use Git Command to generate website, connect to GitHub and push web pages to it.

Step 1 : Generate pages locally

1.1 Install Hugo

Go to Hugo Installation Page , and find the corresponding installation for the operating system you’re using.

I’m using Windows and I haven’t installed Chocolatey or Scoop, so I installed Hugo using binary files following this installation tutorial . If you’re in the same case as mine, you may follow the steps below to install Hugo.

In the following steps, YourUserName refers to the user name of your Windows-system computer. More specifically, it’s the name displayed on the screen when you login in Windows.

(1) Go to folder C:\Users\YourUserName, and create a bin folder in it if it doesn’t exist. The bin folder is the place to store the Hugo binary file.

(2) Add the bin folder to PATH. In Windows Taskbar Search Box, enter cmd and select the Command Prompt result ( right click and choose the “Run as administrator” option ). In Command Prompt, enter :

setx PATH "C:\Users\YourUserName\bin;%PATH%"

Then close and reopen the Command Prompt again, enter echo %PATH% to check if bin has been successfully added to PATH.

(3) Download .zip file from Hugo release page on GitHub . Be Sure to choose the extended version, which will be found near the bottom of the list of archives.

From the .zip extract the binary file hugo.exe and move it to the bin folder. After that, open Command Prompt and enter :

hugo version

If Hugo is successfully installed, you will see a series of characters about information including Hugo version, operating system, build date.

1.2 Create a Hugo site

Supposing you use FolderA to store your site files. Right click FolderA, and select “Git Bash Here” in the menu to open the Git Bash Command. Now enter:

hugo new site MySite

Then a new folder named MySite will be created in FolderA, that is your Hugo site.

1.3 Pick a theme and configure the site

Since a new site has been created, maybe you’d like to see what your Hugo site looks like, but wait a minute, you have to choose a theme first.

What is a theme?

You can regard it as the design of your website. Hugo Themes site has many different themes. When you pick a theme, you can download it from its GitHub repository.

How to pick a theme?

Here I’d like to give you some advice to save your time on choosing themes, for I’ve spent a lot of time on Hugo themes, picking one, configuring it and then changing to another one.

(1) A theme that has an exampleSite folder is easier to use. Different themes have different settings, for example, on choosing which folder to store the posts. The most important file in exampleSite is the config.toml ( or config.yml, or config.json ) file, which provides an example for your configuration, so you know which parameters to tweak to get the desired result. Without exampleSite, you’ll need much more time to configure it.

(2) When previewing the theme, you need pay attention to some features that you’ll use. For example, if you write technical articles, you should check whether the theme displays Math equations and highlights code blocks well.

After I pick a theme, how to configure it?

Copy the theme folder you’ve downloaded into MySite > themes folder.

If the theme folder contains exampleSite, you can copy the files in exampleSite to MySite folder. After that, copy other folders except exampleSite ( especially archetypes, layouts, static folders ) to MySite folder.

Some themes don’t have exampleSite. If you’re a beginner, I don’t recommend you to use it now, because you’ll spend much more time to figure out how to set the parameters. When I wrote this article, I was using Hyde as the theme of my site . I like its simple design. It doesn’t have exampleSite . However, I have used several themes before, so I used config file of the previous themes and changed some parameters to set as the Hyde Theme.

Then Open Git Bash Prompt on MySite folder, and enter :

hugo server

When it’s done, open the URL displayed in your terminal, and you’ll see the example site locally. If you change the parameters in config.toml, the page will make corresponding changes at the same time. In this way, you can configure your site.

In the future, when you write a new post or make some revisions, you can still use hugo server to view your site locally before pushing to GitHub.

1.4 Write posts

To create a new post, open Git Bash Command on MySite folder, and enter :

hugo new new_post.md

It will create a new markdown file named “new_post” in MySite > content folder. But if you use hugo server, you may not see the new post. Why?

(1) Depending on the theme you choose, you may need to put the new_post.md into post (or posts ) folder in the content folder to generate the web page. In this case, you can also enter the following command to create a new post :

hugo new post/new_post.md

(2) Open the new post in your editor (Typora, VS Code, etc). In the header of the post , there are settings about the post (it’s also called front matter). Find draft: true , which means this post is a draft and you don’t want to publish it now. Change it to draft: false so that the post will be published on the site. Besides, the title in the header refers to the title of the post, and it is set to be the file name when created (for example, “new_post” here) . You can change it to whatever you want in your editor.

1.5 How to display images?

Although many tutorials didn’t mention how to insert and display images, I think for beginners it’s an important part in the building process, for you may add pictures to make your article easier to understand or look better.

1. For local images

In Hugo, the local images are stored in MySite > static folder in order to be displayed. Supposing you have an image named image1.jpg, after putting it into the static folder, you can insert it in your post this way :

![image1_title](/image1.jpg)

Or you may put all images in one folder : MySite > static > imgs, then insert the image in your post by :

![image1_title](/imgs/image1.jpg)

But the above method doesn’t display the title of the image. If you want to show the title along with the image, you can use :

{{< figure src="/image1.jpg" title="image1_title" >}}

Here please notice the space between the angle brackets ( < and > ) and the content.

The pipeline figure you’ve seen in “Site-Building Pipeline” Section was inserted in this way.

2. For web images

If your image is stored on the web, you can insert the image using its web link by one of the three ways below:

Way-1: show the image without the title
![image2_title](image2_weblink)

Way-2: show the image with the title
{{< figure src=image2_weblink title=image2_title >}}

Way-3: show the image without the title
<img src=image2_weblink alt=image2_title align=center />

In way-2 and way-3, there are no double quotes around image2_weblink or image2_title, i.e. write image2_weblink, not “image2_weblink”.

You may look at the post on my site to look at the example of web image display.

Step 2 : Deploy the site to GitHub

2.1 Create a GitHub repository

Log in GitHub and create a public repository named YourGitHubName.github.io, this is where you’re going to store your web pages on GitHub so that others can view your site. Here please make sure YourGitHubName is the same as your GitHub username.

2.2 Build your site and push it to the repository on GitHub

I followed the steps introduced in this tutorial .

Things you need to do before deploying for the first time:

For the first time, you need to connect MySite > public folder to your GitHub repository. The public folder is the place to store your site files after they are generated by Hugo. Connect it to your GitHub repository, so that the site files will be synchronized on GitHub.

Open Git Bash Command on MySite folder, enter :

cd public
git init
git remote add upstream https://github.com/YourGitHubName/YourGitHubName.github.io.git

After that, set the parameter baseurl in config.toml to be your GitHub repository above :

baseurl = "https://YourGitHubName.github.io/"

The following are the things you do every time you push your site to GitHub:

First generate the site files:

Open Git Bash Command on MySite folder, enter :

hugo

When it’s done, Hugo will generate the site files and store it in the public folder.

Then we’ll push these files to GitHub, continue to enter:

cd public
git add .
git commit -m"your_commit_message"
git push upstream master

The above commands use git remote add upstream... and git push upstream master, I also used these two commands. I saw a tutorial use origin instead of upstream, i.e. git remote add origin... and git push origin master, which also works. You may have a try.

Future Work

Some tutorials introduced GitHub Actions for automating the deployment, and next I’m going to learn it.

References

Hui Gong: How to build personal blog using GitHub Pages and Hugo
Flavio Copes: How to start a blog using Hugo
Hugo installation : https://www.brycewray.com/posts/2022/10/how-i-install-hugo/
Set the Hugo theme quickly: https://www.tomasbeuzen.com/post/making-a-website-with-hugo/ (I wish I had read the step 4 in it about the configuration of website earlier, it’s efficient.)
Deploy Hugo site to GitHub: https://jdhao.github.io/2018/10/10/hexo_to_hugo/

What’s the Return Value of a Bool Expression in Python?

JulieS — Fri, 17 Feb 2023 12:40:18 +0000

We know that the boolean value of 0 is False, and the boolean value of 1 is True. What about the boolean value of a negative number, for example, -2 ? What‘s the result of the expression True and 3 in Python? Is it True or False, or other value? Let’s find it out.

1. Boolean Value

Here is a question I came across while I was doing a lab of Berkeley CS61A Course . What would Python print?

>>> positive = 28 

>>> while positive: 

...     print("positive?") 

...     positive -= 3

I thought that after printing “positive?” 10 times , the variable “positive” would become negative, so the program would stop. But my answer didn’t pass the test, so I ran it locally to see what happened. To my surprise, the program didn’t stop! It’s an infinite loop. Why?

Because the boolean value of a negative number is True. Only the boolean value of 0 is False, while the boolean value of a positive or negative number is True, so bool(-2)=True .

In Python, the boolean value of False (or 0, or ‘’, or None) is False. The boolean value of others is True.

Then how to evaluate the bool expression?

2. Bool Expression

A bool expression usually contains logic operators such as and, or, not.

(1) `<exp1> and <exp2>`

The result of False and True is False, so for the expression <exp1> and <exp2> , only when the value of the first element <exp1> is True do we need to check the second element <exp2> . For example, the value of True and 0 is 0.

That is, and stops evaluating at the first false value. For example:

>>> 0 and 2
0
>>> False and -2
False

If all values evaluate to be True, the last value is returned. So the value of expression True and 3 is 3, while the expression 3 and True returns True. The following is another example of and between two numbers:

>>> 2 and -3
-3
>>> -3 and 2
2

From the results above, you‘ll see that the return value of a bool expression like <exp1> and <exp2> is not always True or False . Take True and 3 as an example, it evaluates the boolean value of <exp1> /<exp2> ( bool(3)=True ), but returns the actual value ( 3 ), so it‘s a number.

(2) `<exp1> or <exp2>`

or expression uses an evaluating order like and expression. The result of True or False is True, so for the expression <exp1> or <exp2> , only when the value of the first element <exp1> is False do we need to check the second element <exp2> .

That is, or stops evaluating at the first true value. For example:

>>> 0 or -1
-1
>>> 2 or -1
2
>>>True or 2
True
>>>0 or False or -3 or 1 / 0
-3

Here the last element 1/0 in the last expression won’t be evaluated, otherwise it’ll produce an error.

If all values evaluate to be False, the last value is returned. For example:

>>> False or 0
0
>>> 0 or False
False

(3) `not <exp>`

Unlike and and or expression, not expression returns the opposite boolean value of <exp>, so the result is either True or False. For example:

>>> not 10
False

Reference:

Lab 1: Variables & Functions, Control | CS 61A Fall 2020

disc01| CS 61A Fall 2020

Beginner’s Guide to Shell Commands

JulieS — Fri, 17 Feb 2023 12:01:25 +0000

Maybe you just began to use Linux, or maybe you need to run programs in Terminal/Shell, in both cases, you need a command reference or cheat sheet. Here’s what you’re looking for, a list of some basic commands with examples.

1. Work on Directories (or Folders in Windows)

ls : list

ls : to list all the directories/files in the current directory(folder).

pwd : present working directory

pwd: to show the current file path.

cd : change directory

cd folder_name: to change directory to the directory(folder).

For example, cd folder1 changes the directory to the subfolder “folder1” in the current folder.

Three special signs for directory:

. : current directory
.. : parent directory, thus cd .. means changing to the parent directory.
~ : home directory, thus cd ~ means changing to the home directory. We can also type cd for the same result.

mkdir : make a directory

mkdir folder_name : to make a new directory (folder).

rm -r : remove

rm -r folder_name : to remove the whole directory (folder) ( “-r” means recursively).

Warning: In UNIX, when you rm a file or directory, it's gone. There is no Recycle bin or Trash for you to "undo" rm, so please think twice before you use it.

2. Work on Files

echo : similar to “print”

echo content : to print the content on the screen.

echo content>>filename.filetype: to write to the file.

cat : display

cat filename.filetype : to display the content of the file.

touch : create a file

touch filename.filetype: to create a new empty file.

The following example uses these three commands. First we use echo to print “hello” on the screen :

>echo "hello!"
hello!

Then we create a new directory named “example”, and use touch to create a new txt file named “ex01” in it.

>mkdir example
>cd example
/example> touch ex01.txt
/example> ls
ex01.txt

When we type cat ex01.txt, the output is nothing, because “ex01.txt” is an empty file.

/example> cat ex01.txt

We can use echo command to write something into “ex01.txt” :

/example> echo "hello">>ex01.txt

Now using cat command, we’ll see the content of “ex01.txt”:

/example> cat ex01.txt
hello

We can also write many times, the content will be added to the file :

/example> echo "Let us learn Python.">>ex01.txt
/example> cat ex01.txt
hello
Let us learn Python.

mv : move

mv source_path dest_path ：to move the file/directory from the source_path to the dest_path.

There are two ways of using mv:

1.mv source_file/directory dest_directory : to move the source file/directory to the dest_directory

2.mv source_file dest_file : to rename the source_file, now the file name is dest_file. If dest_file has already existed, it will be overwritten as the content of the source file.

Let’s see an example. Here we still use the “example” folder in the previous example, with “ex01.txt” inside it.

/example> ls
ex01.txt

First we create a new folder named “sub_example” as the dest_directory.

/example> mkdir sub_example
/example> ls
ex01.txt  sub_example/

The folder “sub_example” is empty now:

/example> ls sub_example

(1) use mv source_file/directory dest_directory to move a file :

/example> mv ex01.txt sub_example

Now the file “ex01.txt” is in the subfolder “sub_example”, not in the folder “example”:

/example> ls
sub_example/
/example> ls sub_example
ex01.txt

(2) use mv source_file dest_file to rename a file :

/example> cd sub_example
.../sub_example> mv ex01.txt ex02.txt

Here the file name is changed from “ex01” to “ex02”.

.../sub_example> ls
ex02.txt
.../sub_example> cat ex02.txt
hello
Let us learn Python.

You may wonder: what will happen if the dest_file has already existed?

We create a file “ex03.txt” with the content “another txt file”.

.../sub_example> touch ex03.txt
.../sub_example> echo "another txt file">>ex03.txt
.../sub_example> cat ex03.txt
another txt file

After typing mv ex02.txt ex03.txt, there will be a prompt to check if you really want to overwrite dest_file “ex03.txt”.

.../sub_example> mv ex02.txt ex03.txt
mv: overwrite 'ex03.txt'? y

If you type “y”, “ex03.txt” will be overwritten as the content of “ex02.txt”.

.../sub_example> ls
ex03.txt
.../sub_example> cat ex03.txt
hello
Let us learn Python.

cp : copy

cp file/directory dest_directory: to copy the file/directory to the dest_directory.

For mv/ cp command, if the dest_directory is the current directory, we can write . instead.

rm : remove

rm file_name: to remove a single file. Here only a file is removed, so -r is not needed.

unzip

unzip file_name.zip : to unzip the .zip file.

3. Others

man command_name: to display manual pages for the command.

Reference

Lab 0: Getting Started | CS 61A Fall 2020

UNIX tutorial | CS 61A Fall 2020

touch command in Linux with Examples - GeeksforGeeks

Forem: JulieS

Hugo: How to Add a Table of Contents(TOC) to Your Post?

1. The TOC configuration

2. How to insert a TOC in the middle of your post?

3. Set the range of headings to be displayed

References

Switching from Hexo to Hugo

1. Hugo v.s. Hexo

2. How I switched from Hexo to Hugo?

2.1. Generate the pages by Hugo locally

2.2. Push to GitHub for the first time

References

How to Build a Personal Website Using GitHub Pages and Hugo?

Site-Building Pipeline

Step 0 : Preparation

Step 1 : Generate pages locally

1.1 Install Hugo

1.2 Create a Hugo site

1.3 Pick a theme and configure the site

1.4 Write posts

1.5 How to display images?

1. For local images

2. For web images

Step 2 : Deploy the site to GitHub

2.1 Create a GitHub repository

2.2 Build your site and push it to the repository on GitHub

Future Work

References

What’s the Return Value of a Bool Expression in Python?

1. Boolean Value

2. Bool Expression

(1) <exp1> and <exp2>

(2) <exp1> or <exp2>

(3) not <exp>

Beginner’s Guide to Shell Commands

1. Work on Directories (or Folders in Windows)

ls : list

pwd : present working directory

cd : change directory

mkdir : make a directory

rm -r : remove

2. Work on Files

echo : similar to “print”

cat : display

touch : create a file

mv : move

cp : copy

rm : remove

unzip

3. Others

(1) `<exp1> and <exp2>`

(2) `<exp1> or <exp2>`

(3) `not <exp>`