Building_with_Hugo

2023-03-06 - 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 sometimes]. This was especially true when trying to structure the site to reference identical posts on multiple pages [ie. on the tots 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 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 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].

After installing on a local machine with apt install hugo [change apt to your respective package manager], a new site can be created with 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 meat 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!].

Hugo posts are written in Markdown which, basically, is a way to define the format of text through some pretty straightforward syntax [trust me, it’s really easy to pick up]. If Markdown’s default behavior is not cutting it for you, it can also be redefined under /layouts/_defaults/_markup.

However, sometimes Markdown doesn’t have all the functionality that html would allow. In these cases shortcodes can be used to inject html into a content page by calling the shortcode with {{< $name_of_shortcode $arg0 $arg1 $arg2 >}}. For example, I have a shortcode to format an image correctly in a post under /layouts/shortcodes/image_sc.html.

    <img class="resize" src="{{ .Get 0 }}" alt="{{ .Get 1 }}" />
    <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}}. Shortcodes are a great way to deal with those edge cases when Markdown just doesn’t quite cut it.

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 [ie xavishobbies.org/web_development/building_with_hugo ] while list templates will are hosted at website.com/section. [ie xavishobbies.org/web_development ]. These templates are written in normal html but can do fancy things with specified functions and variables. Here is my very simple single template.

{{ define "main" }}

    <div class="tots_post">
    	<h3 class="entry_heading">{{ .Title }}</h3>
    	<h5 class="tots_date_category"> {{ .Lastmod.Format "2006-01-02" }} - {{ .Description }}</h5>
    
    	
    	<p>{{ .Content }}</p>
    	
    </div>
{{ end }}

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. It loops through all the posts in a section and displays the title of each post as a link to the full post.

// <!-- Ranges through content/posts/*.md -->
    {{ range .Pages }}
        <li>
            <a href="{{.Permalink}}">{{.Date.Format "2006-01-02"}} | {{.Title}}</a>
        </li>
    {{ 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}}, with the date, {{.Date.Format "2006-01-02"}}, and the title, {{.Title}}.

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" . -}}.

<footer> <a href="{{ .Site.BaseURL }}/index.html">Home</a> </footer>

Again, the whole point is to eliminate redundant code wherever I can without creating a boring cookie cutter site.

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. 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!

Gitea_Install

2023-02-27 - Web Development - Git Server

If you haven’t heard of Git it’s a pretty [at this point] universal versioning control system [basically it makes sure it keeps backups of everything when you accidentally break everything and want to reset it]. The short version of it is that you can use git locally, but a more common method is to push the repository [fancy way to say folder] to a remote server. Then, you can work on multiple systems [or save yourself when you accidentally delete the local copy] by using the remote server as a place to push and pull changes.

The most common website [at least I think it is] to host repositories is Github. Github is a great service that is probably a perfect solution for most people. But we aren’t most people. Aside from the benefit of learning a system like git from a server-side perspective, hosting our own instance allows for complete control of content, look, visibility of repos, and… well everything.

It’s actually fairly simple to set up a git server if you aren’t looking for a fancy GUI and are willing to work from the terminal. I have no fear of the terminal but I do think it would be easier to share my code with others by having a frontend that is easy to browse through. However, my frontend development skills need a bit of work [maybe you can tell from this website]. Luckily, there is a pretty OOTB [Out of the box] solution with Gitea .

Gitea is pretty simple to install, although it looks like it isn’t in the Debian repos so some extra steps had to be taken. The Gitea gitlab has some good documentation on getting it going. Run [if you are also using a debian system as your server] these commands to get Gitea running locally on your server.

sudo curl -sL -o /etc/apt/trusted.gpg.d/morph027-gitea.asc https://packaging.gitlab.io/gitea/gpg.key`

echo "deb https://packaging.gitlab.io/gitea gitea main" | sudo tee /etc/apt/sources.list.d/morph027-gitea.list`

sudo apt-get update && sudo apt-get install gitea morph027-keyring`

systemctl enable --now gitea

You can check that its working by going to http://localhost:3000. And that’s pretty much it [hey! that was easy] to get it running locally [we aren’t done. liar.]. Now we have to mess with our nginx server to set up a reverse proxy [that sounds complicated]. Luckily that’s also not to bad to do [oh]. All that needs to be done is to add a couple lines to the nginx.conf of your website. In my case I would like my Gitea instance to be hosted at https://xavishobbies.org/git/. So I would add a new location at /git/ and define proxy pass to where Gitea is hosted locally. The enitre change would look somthing like this.

    location /git/ {
        proxy_pass http://localhost:3000/;
    }

Then restart the nginx server and you should be able to reach Gitea and get started hosting your own repositories. Poke around my instance. I changed my css to match the theme of this website a bit more but all the other options are pretty much left at default.

Lots_of_Changes

2023-02-19 - Web Development - Medley

Lots of new updates to write up and lots of new features! I’ll make up some guides on how things were done but here is a quick run down of the pretty significant changes that were made.

First things first, we finally have a code repository that will host all the code [regardless of how bad it is] for the projects I am currently working on. This was implemented using Gitea which was pretty quick to implement, especially considering the features it provides.

Next, we also have videos! I'm currently using a Peertube instance to host them. I just threw up an old Linux installation guide I made to test it [Probably riddled with mistakes. Don’t… Don’t watch it].

And finally, I’ve switched over to using Hugo. This didn’t actually add anything new for you guys [Sorry :( ] but it does allow me to really easily add new posts without wrestling with rewriting html multiple times across multiple pages.

I’ll write much more in depth guides for each of these but have a look around my code and checkout the Peertube instance [although maybe don’t watch the video yet] while you wait.

What’s that? You don’t believe me [I've been gone? What? You're crazy!]

Cloudflare_Died

2022-06-21 - Web Development - Administration

What unfortunate timing! I was about to writing up this post when I lost access to my VPS because Cloudflare went down. Here is the Cloudflare postmortem where they discuss what happened.

It looks like they where trying to "[roll] out a change to standardize [their] BGP" and, from my understanding [which I would take with about a cup of salt], moved the reject condition above "site-local terms". So the request would be rejected before being able to reach origin servers [as opposed to an edge or caching server].

I might look more into BGP because I don't know about it at all. One for the stack I suppose.

Online!

2022-06-06 - Web Development - Administration

Hopefully you can see this because that means that I didn't mess anything up when updating the site! I'll quickly recap what I did over the last week and clarify what's in the pipeline for this upcoming week.

So I ended up destroying and remaking the Vultr VPS [Virtual Private Server if I didn't clarify that previously] so that I could have a fresh, clean environment to start messing around in. I decided to go with their smallest, and cheapest plan to start things off [I think it can handle the traffic that I expect to start "pouring" in].

I found this video that explained how to calculate how much needed bandwidth I needed to budget for. Again I don't think I need much [something tells me I'm the only one checking in on this website 100 times a day]. I stuck with a Debian distribution for no reason in particular other than it's what I used previously on other VPSs [if your unfamiliar with Linux and Linux distributions I'll make some intro to Linux guides in the future that'll explain all the common nerd jargon].

I grabbed the domain name from dynadot and changed the DNS records to have it point to the IP of the VPS. I'll write up a full guide for this in a bit [honestly it's pretty easy]. I then installed nGinx, changed the config files to point to the html/css files, and started the service [kinda skipped the nitty gritty but again, guide incoming].

I was able to visit the site at this point from a client device but still had to set up SSL [Secure Sockets Layer] so that the connection was encrypted. Apparently it was pretty uncommon in the past to have encrypted connections on personal websites but that was changed with the help of the EFF with let's encrypt which offers free, open certificates [pretty cool of them honestly]. To make things even easier they also provide a python script(?) called certbot which automates the process of obtaining one of these ssl certificates. After I ran it I got the cool green lock icon in the address bar and was feeling pretty cool myself! :)

Those were the major updates for this week. Next week I'll be looking into hosting a git server to upload my code [including anything that I create for this website ie. html/css/scripting stuff] and a git visualiser. Hosting a git server seems easy enough but finding the right visualiser might need a bit more research. Right now the most promising candidate is stagit which is a static git page generator. Hope that works out.

The stretch goal for this week is the possibility to host videos with [maybe?] a peertube instance. Not sure how much of a pain and/or the bandwidth limitations will throttle the experience too much but it sounds useful to post, even short, videos demonstrating processes explicitly [if a picture is 1000 words than what does that make a video].

That's the update for the week.

Next TODOS! [Can be updated throughout the week]

• Look into hosting git server
• Set up gitolite for git permissions
• Set up stagit for git visualization
• Possibly Peertube for embedded videos