Xavi/xavishobbies
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Modified building with hugo

Browse Source
This commit is contained in:
Xavi 2023-03-06 11:02:56 -08:00
parent 582428fee2
commit e869419213
1 changed files with 18 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
xavishobbies/content/web_development/building_with_hugo.md
View File

@ -6,11 +6,11 @@ categories: ["Top_of_the_Stack"]
tags: ["Web Development","Hugo"]
---
As much as I started to enjoy playing around and styling with *html/css*, it did, at times, become slightly annoying to quickly document progress on projects **[which is hard enough to do as it is]**. This was especially true when trying to structure the site to reference identical posts on multiple pages **[ie. on the [tots](https://xavishobbies.org/categories/top_of_the_stack/) page as well on the associated hobby page]**. A solution that I have been mulling from the beginning is a *static site generator*.
As much as I started to enjoy playing around and styling with *html/css*, it did, at times, become slightly annoying to quickly document progress on projects **[which is hard enough to do as it is sometimes]**. This was especially true when trying to structure the site to reference identical posts on multiple pages **[ie. on the [tots](https://xavishobbies.org/categories/top_of_the_stack/) page as well on the associated hobby page]**. A solution that I have been mulling from the beginning is a *static site generator*.
What I was looking for was an environment that was *extensible* enough to eliminate redundant code while also *malleable* enough to execute the initial vision I had for the website **[i know, surprising this website had any vision given the look]**. Static site generators enable this by, essentially, copying identical html across multiple pages through *templates*. This maintains the benefits of a static site while addressing one of it's biggest drawbacks. After some research **[googling "best static site generator"]**, [Hugo](https://gohugo.io/) seemed to check the boxes I had in mind while also seeming relatively simple to implement **[which is something a lazy person like me really values]**.
What I was looking for was an environment that was *extensible* enough to eliminate redundant code while also *malleable* enough to execute the initial vision I had for the website **[i know, surprising this website had any vision at all given the look]**. Static site generators enable this by, essentially, copying identical html across multiple pages through *templates*. This maintains the benefits of a static site while addressing one of it's biggest drawbacks. After some research **[googling "best static site generator"]**, [Hugo](https://gohugo.io/) seemed to check the boxes I had in mind and also looked relatively simple to implement **[which is something a lazy person like me really values]**.
*Hugo* is structured hierarchically and has a couple main directories where content is pulled to generate pages. *Content*, where the actual content of a *post* is stored, *layouts*, where *templates* and other *code snippets* are defined, and *static*, where things like *images* referenced in posts and *style sheets* are contained.
After installing on a local machine with `apt install hugo` **[change apt to your respective package manager]**, a new site can be created in *Hugo* with the command `hugo new site site_name` which creates a directory with Hugo's default file structure. The main directories that I use are *content*, *layouts*, and *static*. *Content* is where the actual content of a *post* is stored **[basically the actual content of the website]**, *layouts* is where *templates* and other *code snippets* are defined **[where hugo pulls the skeleton html to generate posts and lists]**, and *static* is where things that are referenced by templates and posts are stored **[like images and style sheets]**.
New content posts can be created with `hugo new section_name/post.md` which creates a new file under *content/section_name/post.md*. For example this post was created with `hugo new web_development /building_with_hugo.md`. Section landing pages can be created by adding a *_index.md* file under the section directory with `hugo new section_name/_index.md` **[these will call the *list* template, if you don't know what that means, *read on!*]**.
@ -23,9 +23,9 @@ However, sometimes *Markdown* doesn't have all the functionality that *html* wou
<figcaption>{{ .Get 2 }}</figcaption>
```
I can utilize this in a post with `{{</* image_sc "path_to_image" "alt_text" "caption" */>}}`. *path_to_image* will be passed into `{{ .Get 0 }}` given its the first argument, *alt_text* to `{{ .Get 1 }}`, and *caption* to `{{ .Get 2}}`.
I can utilize this in a post with `{{</* image_sc "path_to_image" "alt_text" "caption" */>}}`. *Path_to_image* will be passed into `{{ .Get 0 }}` **[given its the first argument]**, *alt_text* to `{{ .Get 1 }}`, and *caption* to `{{ .Get 2}}`. *Shortcodes* are a great way to deal with those edge cases when *Markdown* just doesn't quite cut it.
The two main templates that I've used are *single.html* and *list.html* **[here it is!]** under the *_default* folder. *Single* is used for *individual posts* while *lists* are used to, well, list the individual posts **[shocker]**. Single pages can be navigated to at [website.com/section/post.md](/web_development/building_with_hugo) while, as referenced earlier, the list template will be used for section landing pages which can be navigated to at [website.com/section.](/web_development) These templates are written in normal html but can do fancy things with specified [functions](https://gohugo.io/functions/) and [variables.](https://gohugo.io/variables) Here is my very *simple single template*.
Now on to *templates*. Templates are also placed under the */layouts* directory. The two main templates that I've used are *single.html* and *list.html* **[here it is!]** under the *_default* folder. *Single.html* is used for *individual posts* while *list.html* is used for section landing pages which list the individual posts **[shocker]** in the section. Single pages are hosted at [website.com/section/post.md](/web_development/building_with_hugo) **[ie [xavishobbies.org/web_development/building_with_hugo](/web_development/building_with_hugo)]** while *list* templates will are hosted at [website.com/section.](/web_development) **[ie [xavishobbies.org/web_development](/web_development)]**. These templates are written in normal html but can do fancy things with specified [functions](https://gohugo.io/functions/) and [variables.](https://gohugo.io/variables) Here is my very *simple single template*.
``` GO
{{ define "main" }}
@ -41,9 +41,9 @@ The two main templates that I've used are *single.html* and *list.html* **[here
{{ end }}
```
Which just inputs the post title at `{{ .Title }}` and content at the `{{ .Content }}` **[pretty straightforward huh?]**.
This just inputs the post title at `{{ .Title }}` and content at the `{{ .Content }}` **[pretty straightforward huh?]**.
And here is a quick example of a *list template* that is referenced in the *Hugo* documentation that loops through all the posts in a section and displays the title of each post as a link to the full post.
And here is a quick example of a *list template* that is referenced in the *Hugo* documentation. It loops through all the posts in a section and displays the title of each post as a link to the full post.
``` GO
// <!-- Ranges through content/posts/*.md -->
@ -54,12 +54,18 @@ And here is a quick example of a *list template* that is referenced in the *Hugo
{{ end }}
```
It uses `range` to loop through all content `.Pages`, and create a list item, `<li>`, with a reference, `<a href=`, to the single content page, `{{.Permalink}}`, as the title, `{{.Title}}`.
It uses `range` to loop through all content `.Pages`, and create a list item, `<li>`, with a reference, `<a href=`, to the single content page, `{{.Permalink}}`, with the date, `{{.Date.Format "2006-01-02"}}`, and the title, `{{.Title}}`.
*Partials* are templates that can be called by other templates such as *single* and *list* and are saved under */layouts/partials*. They can be called with the `partial` keyword. For example, I use partials to handle my footer and can call it from both my *single.html* and *list.html* with `{{- partial "footer.html" . -}}`.
*Hugo* also uses *partials*, which are templates that can be called by other templates such as *single* and *list* and are saved under */layouts/partials*. For example, I use a partial to handle my footer which I call from both my *single.html* and *list.html* with `{{- partial "footer.html" . -}}`.
The main website *landing page*, *404 page*, and other *special content* can also be defined under the layouts directory which will supersede any previously defined templates.
``` GO
<footer> <a href="{{ .Site.BaseURL }}/index.html">Home</a> </footer>
```
With all that defined and out of the way, if you are ready to take a look at you page locally, `hugo server` can be run which will start an instance of your website on [localhost:1313.](http://localhost:1313)
Again, the whole point is to eliminate redundant code wherever I can without creating a boring cookie cutter site.
That's pretty much everything that's utilized to build this site. Hope it wasn't too much of an info overload!
Then again some pages need to be completely unique. Things like the main website *landing page*, *404 page*, and other *special content* can be written completely in html and placed under the layouts directory. These special pages will supersede any previously defined templates.
*Hugo* also lets you take a look at your site locally, before pushing it to a live site, with the `hugo server` command. This starts an instance of website at [localhost:1313.](http://localhost:1313) Just throw that into the browser of your choice and take a gander. What's also super cool is that *Hugo* detects changes and auto generates the site every time it does. This lets you actively see the changes you are making **[or for me, shows me how my formatting is wrong, AGAIN]**.
That's pretty much everything that I used to build this site. Hope it wasn't too much of an info overload!