Showing Posts From

Learninghugo

Displaying full content in rss.xml in Hugo

Create a new file at layouts/_default/rss.xml. You can define your rss.xml as per your liking. By default rss.xml only displays the summary of your articles. But I want to display the whole content. This helps me in syncing my posts with my dev.to site. You can find the Hugo's default rss.xml at Hugo's Github repo. Let's copy the contents to our rss.xml file that we just created. Then change the description to show content instead of summary as follows. -<description>{{ .Summary | transform.XMLEscape | safeHTML }}</description> +<description>{{ .Content | transform.XMLEscape | safeHTML }}</description>Before the changes there were only 504 characters in the characters. curl localhost:1313/index.xml | grep "description" | head -n 3 | tail -n 1 | wc -c: 504After the changes the number of characters increased significantly as the whole blog is being rendered in the description. curl localhost:1313/index.xml | grep "description" | head -n 3 | tail -n 1 | wc -c: 14582

Partials in Hugo

Partials and code reusability Hugo provides a nice mechanism to separate your components and stitch them at different places. This means you can design your components like nav-bar or menu bar and stitch them in all of your layouts. Earlier, we wrote some code to load tailwind in our index page. But we do not want to write this boilerplate code for all our pages. Instead we should have defined the tailwind loader code in a component and call it from all the layouts. Actually, we should have called the boilerplate code from baseof.html from which all other layouts are inherited. baseof.html When we created the theme, a special file was created for us, baseof.html. Every other layout inherits baseof.html. If you look at the contents of baseof.html which was generated for use. You will find 3 partial sections, head, header and footer. These are the default standards but you will go on creating partials as your code base becomes more complex. The main block denoted by {{ block "main" . }}, is where your content from other pages will be inserted. You can define your layout as main in other layout files and that block will be inserted here. <!DOCTYPE html> <html> {{- partial "head.html" . -}} <body> {{- partial "header.html" . -}} <div id="content"> {{- block "main" . }}{{- end }} </div> {{- partial "footer.html" . -}} </body> </html>You can ignore the dashed infront and at last of the decalrations. These are the guide for Hugo to trim spaces infront and back.head.html After html tag we have a partial head.html instead of a head tag. Hugo is smart enough to generate head attribute from the partial. Looking closely, it just process your partials and replaces the partial block with it. We could have defined out tailwind loading code here as follows. Now we got the support for tailwind everywhere in our site. You can also define some meta tags or other libraries here. <head> {{ with resources.Get "css/main.css" }} {{ with . | css.TailwindCSS }} <link rel="stylesheet" href="{{ .RelPermalink }}"> {{ end }} {{ end }} </head>Defining custom partials Defining partials is as easy as it can be. You just need to create a file under partials directory. And write whatever processing you want to do. And include it in you main layout using {{ partial "your-file.html" . }}. You can pass any data along with your partial definition. In the above partial definition, we are passing the current context to our partial. Make CSS styling a partial Let's create a new partial by creating a file called css.html. This will contain the logic to process and import our tailwind libraray. The contents of css.html will be as follows. {{ with resources.Get "css/main.css" }} {{ with . | css.TailwindCSS }} <link rel="stylesheet" href="{{ .RelPermalink }}"> {{ end }} {{ end }}And our head block will include this as a partial as follows. The below code goes inside baseof.html. <head> {{ partial "css.html" . }} </head>Modify the pages to use baseof You will need to define the main block in all your layouts. This will help Hugo to link the contents of layouts page and combine it with baseof to generate the rendered page. Below is how, I modified my index.html page. {{ define "main" }} <p class="text-red-500">This paragraph is red.</p> {{ .Content }} {{ end }}curl localhost:1313 | grep "main.css": <link rel="stylesheet" href="/css/main.css">This looks as expected. We can see out main.css linked to our homepage. Now let's modify the list.html layout and define main here as well. {{ define "main" }} <ul> {{ range .Pages }} <li>{{ $.Site.Title }} - {{ $.Title }} - {{ .Title }}</li> {{ end }} </ul> {{ end }}curl localhost:1313/posts/ | grep "main.css": <link rel="stylesheet" href="/css/main.css">Awesome, we can now use tailwind from anywhere in our website. Summary In this post we explored partials which is basically a way of reusing the code in Hugo. We learned about baseof.html which is inherited by all the layouts. We combined our tailwind learning with partials and created a css.html partial which can now be used from anywhere.

Tailwind support in Hugo

Expectations from this post With the version 0.128.0, Hugo started supporting Tailwind internally. In this post, let's configure Tailwind and display some text in red. Tailwind and other supporting apps We will install the below 4 packages.tailwindcss - This is the core Tailwind library and is required for using tailwind tailwind/cli - This is a CLI tool for Tailwind that helps in building tailwind styles postcss - This is a library to process CSS with JavaScript plugins. autoprefixer - This is a postcss library that helps in automatically generating the vendor prefixes like -webkit- and -moz-.We will install these packages as dev as they play no role after building the site. npm install --save-dev tailwindcss @tailwindcss/cli postcss autoprefixerPostCSS config You need to specify the plugins for postcss. This can be done by creating a file, postcss.config.js. You can add the plugins you want to use here as follows. For now, we will add tailwindcss and autoprefixer as the plugins. plugins: { tailwindcss: {}, autoprefixer: {}, }, };Tailwind config We can create a more advanced config for Tailwind later. For now, let's just create a file, tailwind.config without any contents in the theme's root directory. Loading Tailwind on the index page Let's first create a resource main.css in the assets directory of the theme. Here we will import Tailwind and then we will load this resource in our index file using some Hugo magic. main.css In the theme's root directory, let's create a directory assets/css and add a file main.css here. The content of the file will just load the Tailwind library. @import "tailwindcss";index.html Here, we just want to add main.css as our stylesheet. This is done by using link tag. First we want to load the resource then we want to process it using tailwind and add it to our page. We can use Hugo's with function to load the file and again using with, we can process the obtained file using tailwind. The below snippet will do the trick. {{ with resources.Get "css/main.css" }} will try to get the main.css file. Hugo will look into the assets direcetry for css/main.css. {{ with . }} will only be processed if the file was found. And if found we can pipe the contents to be processed by css.TailwindCSS provided by Hugo. {{ with resources.Get "css/main.css" }} {{ with . | css.TailwindCSS }} <link rel="stylesheet" href="{{ .RelPermalink }}"> {{ end }} {{ end }}This would be enough to start using Tailwind functionalities. To test if it is working of not, we can add a simple text and use some tailwind features to make it red. Inside the index.html, body let's add the following. Adding class as text-red-500, should turn the content of <p> to red. <p class="text-red-500">This paragraph is red.</p>Taking a peek Let's first curl the homepage and verify of link was created successfully. curl localhost:1313<html> <head> <meta name="generator" content="Hugo 0.144.2"><script src="/livereload.js?mindelay=10&amp;v=2&amp;port=1313&amp;path=livereload" data-no-instant defer></script> <title> Shubham&#39;s corner </title> <link rel="stylesheet" href="/css/main.css"> </head> <body> <p class="text-red-500">This paragraph is red.</p> </body> </html>The file main.css here is the processed main.css and will look very different than what we have written.This is good, next let's see the actual site.The rendered text is red which means we were finally able to load out Tailwind. Summary In this post, we saw how to enable the support of Tailwind CSS in out Hugo site. We added some text and turned it to red using Tailwind classes. Next, we will explore code re-usability in Hugo which is where partials come to play.

Hugo context

What we did and what we will do? Previously, we were successfully able to render our home, single and list pages. When we started templating, we looked into a term called, context. We worked with site context and page context and I assumed they are just like references. This post is meant to explore more on context and get a deeper understanding. Context The Context is the object available to you at anytime. This means, if you are in a single page then the context available to you will be the contents of the page, it's title and other related information. On one of the list pages, the context will contain a collection of items. Title and Contents There are some page related contexts like .Title and .Contents which can be used form any one of the layouts. I can change the index.html or single.html or list.html and print the title and contents. I do not have any content in my home page and lists pages right now, so the body will be blank. But for, any one of the blogs we can check the contents being rendered. <html> <head> <title> {{ .Title }} </title> </head> <body> {{ .Content }} </body> </html>curl http://localhost:1313/posts/designing-my-own-theme-in-hugo-ii/ | head -n 10<html> <head><script src="/livereload.js?mindelay=10&amp;v=2&amp;port=1313&amp;path=livereload" data-no-instant defer></script> <title> Designing my own theme in Hugo - II </title> </head> <body> <h2 id="what-we-did-and-what-we-will-do">What we did and what we will do?</h2> <p>This is a part blog in which I am documenting my learning process of creating my own theme in Hugo. Previously, we went through the basic flow of creating a theme.Accessing the site contexts If you want to access the site related information, like the title for your site or any property defined for your site in config.toml, you can use the .Site context. Basically, each page contains a data related to your site inside {{ .Site }} object. Changing the title to {{ .Site.Title }} started displaying me the site's name, which is Shubham's corner. <html> <head> <title> {{ .Site.Title }} </title> </head> <body> {{ .Content }} </body> </html>curl http://localhost:1313/posts/designing-my-own-theme-in-hugo-ii/ | head -n 10<html> <head><script src="/livereload.js?mindelay=10&amp;v=2&amp;port=1313&amp;path=livereload" data-no-instant defer></script> <title> Shubham&#39;s corner </title> </head> <body> <h2 id="what-we-did-and-what-we-will-do">What we did and what we will do?</h2> <p>This is a part blog in which I am documenting my learning process of creating my own theme in Hugo. Previously, we went through the basic flow of creating a theme.Change of contexts There are certain functions which changes the current context. If we want to iterate over all the pages in page list. Then you use range method. The range method provides you an iterator for you collection. If I want to display the title of all the collections in my posts. I can provide a range block as follows. <body> {{ range .Pages }} {{ end }} </body>.Pages provides me a collection of page objects for each of the pages in the list. In between the blocks, my context is changed to the currently iterated page. This means, calling .Title in b/w the blocks will render the title of pages in collection one-by-one. <body> <ul> {{ range .Pages }} <li>{{ .Title }}</li> {{ end }} </ul> </body>curl http://localhost:1313/posts/<html> <body> <ul> <li>Hugo context</li> <li>Designing my own theme in Hugo - II</li> <li>Designing my own theme in Hugo - I</li> <li>Julia and basic matrix operations</li> <li>AOP in pure Java, keeping logging simple and aside</li> <li>Object pool design pattern in Java</li> <li>Downloading a single file from 2 independent apps</li> <li>Syncing org roam files across devices in WSL2 environment with better performance</li> <li>Reflection API in Java</li> </ul> </body></html>You can still access the global contexts by using the $ symbol. $.Title will refer to the title of this page. $.Site.Title will refer to the site's title. <li>{{ $.Site.Title }} - {{ $.Title }} - {{ .Title }}</li>curl http://localhost:1313/posts/<html> <body> <ul> <li>Shubham&#39;s corner - Posts - Hugo context</li> <li>Shubham&#39;s corner - Posts - Designing my own theme in Hugo - II</li> <li>Shubham&#39;s corner - Posts - Designing my own theme in Hugo - I</li> <li>Shubham&#39;s corner - Posts - Julia and basic matrix operations</li> <li>Shubham&#39;s corner - Posts - AOP in pure Java, keeping logging simple and aside</li> <li>Shubham&#39;s corner - Posts - Object pool design pattern in Java</li> <li>Shubham&#39;s corner - Posts - Downloading a single file from 2 independent apps</li> <li>Shubham&#39;s corner - Posts - Syncing org roam files across devices in WSL2 environment with better performance</li> <li>Shubham&#39;s corner - Posts - Reflection API in Java</li> </ul> </body></html>Summary In this post, we explored in depth on contexts. We saw, {{ . }} refers to the current context. For pages, the context provides the title and other related information. We also witnessed the change of context while using range function and also used $ symbol to get the global context. Next, we will explore styling the site using CSS.

Designing my own theme in Hugo - II

What we did and what we will do? This is a part blog in which I am documenting my learning process of creating my own theme in Hugo. Previously, we went through the basic flow of creating a theme. My current theme is poison theme and we replaced the theme with our new theme which we named, "awesometheme". But unfortunately, after applying the new theme, the rendered page was blank. And in this post, we will expand our knowledge of Hugo and lean to render single pages. Layout and content separation Hugo architecture keeps content separate from the layout. This allows me to keep my blog post contents as it is and apply a new theme on the top of it. There are 3 general pages and for each page there is a layout. These pages are home page, single page and list pages. The home page is the landing page of your site. For a blog site, it can be the introductory page with list of recent blogs. The single page defines a page with content. For example, the blogs itself. And list pages are the pages that displays the list of items. For example, a list of blogs ordered in some preference. You can define and customize more pages based on your preference but these are the basic ones. As I already have the content ready, let's explore the layout designs first. Homepage The home page layout is defined under layouts/index.html. Currently, there isn't anything present in my index.html. Let's write something arbitrary in it and check if something happens. <html> <head> <title>Shubham's Blog</title> </head> <body> <div>Hi all,</div> <div>How are you guys</div> </body> </html>curl localhost:1313<html> <head> <meta name="generator" content="Hugo 0.92.2" /><script src="/livereload.js?mindelay=10&amp;v=2&amp;port=1313&amp;path=livereload" data-no-instant defer></script> <title>Shubham's Blog</title> </head> <body> <div>Hi all,</div> <div>How are you guys</div> </body> </html>Now, I can see the title and body as I defined. List Layout Let's try to render a list of blogs. The _default/list.html defines a default layout for all the list items. I can enter any HTML code and it will be displayed. But I want to do something more. I want to iterate through all the blog contents which I keep in posts directory and create a link for the blog page. This is where Hugo uses GoLang's templating library. Anything beginning with a . refers to the current context. I will explore more on contexts later. The reference, .Pages contains a list of all the pages for this section. So if, we are referring to posts directory, then .Pages will contain all the blogs inside the posts directory. The for-loop is done using range keyword. The range keyword iterates through a list and changes the context to the current item. So calling .Title inside the range block will refer to the current blog's title. We can do something as follows. <html> <head> <title>Shubham's Blog</title> </head> <body> <div>List of my recent posts ...</div> <ul>{{range .Pages}} <li>{{.Title}}</li> {{end}} </ul> </body> </html>curl http://localhost:1313/posts/<html> <head><script src="/livereload.js?mindelay=10&amp;v=2&amp;port=1313&amp;path=livereload" data-no-instant defer></script> <title>Shubham's Blog</title> </head> <body> <div>List of my recent posts ...</div> <ul> <li>Designing my own theme in Hugo - II</li> <li>Designing my own theme in Hugo - I</li> <li>Julia and basic matrix operations</li> <li>AOP in pure Java, keeping logging simple and aside</li> <li>Object pool design pattern in Java</li> <li>Downloading a single file from 2 independent apps</li> <li>Syncing org roam files across devices in WSL2 environment with better performance</li> <li>Reflection API in Java</li> </ul> </body> </html>Single page layout The single pages like the actual blog post layout can be defined inside, _default/single.html Same as what we did in the list layout, we can call .Content to display the content of the current page. <html> <head> <title>Shubham's Blog</title> </head> <body> {{.Content}} </body> </html>And awesome, I can see my contents as well. curl http://localhost:1313/posts/designing-my-own-theme-in-hugo-i/ | head -n 10<html> <head><script src="/livereload.js?mindelay=10&amp;v=2&amp;port=1313&amp;path=livereload" data-no-instant defer></script> <title>Shubham's Blog</title> </head> <body> <h2 id="hugo-is-all-about-themes">Hugo is all about themes</h2> <p>Hugo is a developers dream of static sites. Whether you are planning on a new blog site or maybe a documentation for a product, you can easily launch a static site using Hugo.</p> <p>The most powerful feature of Hugo is its simplicity. It is designed to separate your content from styling.Summary This post allowed us to display the contents of our blogs. We saw, how to design our layout for 3 basic types of pages, homepage, list page and single page. We explored some of the GoLang's templating features and got a shallow understanding of contexts. Next, let's make our blog more dynamic and good looking.

Designing my own theme in Hugo - I

Hugo is all about themes Hugo is a developers dream of static sites. Whether you are planning on a new blog site or maybe a documentation for a product, you can easily launch a static site using Hugo. The most powerful feature of Hugo is its simplicity. It is designed to separate your content from styling. This means you can write your content in normal markdown files independent of all the website pages and layouts. The actual design of the website can be stored as a separate theme. And as it is independent of the content, you can easily switch themes without ever thinking about your content. Creating a new theme To create a new theme, you can just use the below hugo command. It will create a new directory under theme with your theme name. hugo new theme <theme-name>The below files will be created on executing the above command. Let's get an idea on what are these files in this blog. . └── awesometheme ├── LICENSE ├── archetypes │   └── default.md ├── layouts │   ├── 404.html │   ├── _default │   │   ├── baseof.html │   │   ├── list.html │   │   └── single.html │   ├── index.html │   └── partials │   ├── footer.html │   ├── head.html │   └── header.html ├── static │   ├── css │   └── js └── theme.toml8 directories, 11 filesThe interesting part are the archetypes and layouts directory. The layout directory contains the template for your pages. A single page template is defined inside single.html. A page containing a list of items like blog posts are defined inside list.html. The archetypes directory provides the defaults for a type of content. When you run hugo new content post/learninghugo, the new file is created using the default template as described in archetypes/default.md, given you don't have any overrides. Applying the theme My blogs are written in Hugo so I can just start experimenting with my blogs theme. This way, I can forget about generating any dummy content for my theme. To tell Hugo to use a theme, you can just update the theme entry in your config. My blog site uses toml, so below are the changes. - theme = "poison" + theme = "awesometheme"Now let's run the dev server using hugo server --buildDrafts. And I got the below error. 2025-02-15 06:00:39.535 +0530 ERROR 2025/02/15 06:00:39 render of "section" failed: "/home/cold/Projects/Personal/blog.shubham.codes/layouts/_default/baseof.html:1:3": execute of template failed: template: cv/cv.html:1:3: executing "cv/cv.html" at <partial "head/head.html" .>: error calling partial: partial "head/head.html" not found ERROR 2025/02/15 06:00:39 failed to render pages: render of "home" failed: "/home/cold/Projects/Personal/blog.shubham.codes/layouts/_default/baseof.html:1:3": execute of template failed: template: index.html:1:3: executing "index.html" at <partial "head/head.html" .>: error calling partial: partial "head/head.html" not foundSeems like, I have overridden the poison theme for customization. But now, I am using my own theme which does not contains the poison partials. And this is causing the issue. Both the error corresponds to my layout's directory. So let's rename layouts to layouts_. And we will need to refactor these layouts as well.And this is why you should always keep your code loosely coupledmv layouts layouts_And it worked. Start building sites … hugo v0.92.2+extended linux/amd64 BuildDate=2023-01-31T11:11:57Z VendorInfo=ubuntu:0.92.2-1ubuntu0.1 | EN -------------------+------- Pages | 13 Paginator pages | 0 Non-page files | 0 Static files | 1014 Processed images | 0 Aliases | 0 Sitemaps | 1 Cleaned | 0Built in 88 ms Watching for changes in /home/cold/Projects/Personal/blog.shubham.codes/{archetypes,assets,content,data,static,themes} Watching for config changes in /home/cold/Projects/Personal/blog.shubham.codes/config.toml Environment: "development" Serving pages from memory Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) Press Ctrl+C to stopBut my screen is blank. Summary In this post, we went thorough the basic flow of creating a new theme in Hugo. Next, we will learn about layouts and implement the single and list layout for the blog.