Posts on ~hedy's home

Moved to home.hedy.dev

hedy.dev@protonmail.com (hedy) — Wed, 10 Apr 2024 05:22:46 +0000

Hello! Please update your feed reader to point to home.hedy.dev/posts/index.xml instead. Thank you for subscribing!

Setting up syntax highlighting for Hugo

hedy.dev@protonmail.com (hedy) — Sun, 22 Aug 2021 00:00:00 +0000

Hugo uses chroma as its syntax highlighter. All you basically need for having your code highlighted is to let chroma put the syntax classes in the generated HTML, for the correct language, and then make sure you have corresponding CSS for those classes.

Let’s start by enabling syntax highlighting in your configuration file.

In your configuration file, config.toml for example, add these settings so you can have your code highlighted and have it recognize Fenced Code Blocks for markdown:

pygmentsUseClasses = true
pygmentsCodeFences = true

Next you have to include the styles. There are two ways to go about this, one is to choose a style from the list of available styles (more on that below), and the second method is to use your own syntax theme.

You can have your own CSS styles, but there are a lot of classes, so if you’re just starting out and want to have it working quickly, you should choose an existing style.

Browse the gallery of available styles and use that style name to save the CSS file into your assets directory:

mkdir -p assets/syntax
hugo gen chromastyles --style=friendly > assets/syntax/main.css

If you’d like to use different styles for dark mode and light mode (like me), then you can change “main.css” to “light.css”, and save the dark mode style to “dark.css”. It doesn’t matter where you put the file, but just remember to use that file name with referencing it later.

You don’t have to put it under the directory “syntax” too, if you don’t want to.

# Apply the styles

You have to link to your CSS file that you’ve just created in your <head>. There are several ways you can do so.

Use a <link> tag and link to the URL of your CSS file, or
directly put the content of your file into a <style> tag.

Here’s how you can do the second method.

{{- $syntaxCSS := resources.Get "syntax/main.css" | minify -}}
<style>
	{{ $syntaxCSS.Content | safeCSS }}
</style>

Assuming your CSS file is at assets/syntax/main.css.

All set for the styling part! Now you can write some content and try it out.

Remember to include the file type when putting code in markdown.

This is not code

```sh
# and this is some sh code
echo 'hi!'
```

# Dark mode and light mode

You can have different styles of syntax highlighting for dark mode and light mode.

First you have to export or save your CSS for dark mode and light mode in separate files . Then, change the part in your <head> where you’ve included the styles:

{{- $syntaxlight := resources.Get "syntax/light.css" | minify -}}
{{- $syntaxdark := resources.Get "syntax/dark.css" | minify  -}}
<style>
	{{ $syntaxlight.Content | safeCSS }}
	@media (prefers-color-scheme: dark) {
		{{ $syntaxdark.Content | safeCSS }}
	}
</style>

This assumes you have your light styles and dark mode styles stored in assets/syntax/light.css and assets/syntax/dark.css respectively.

Instead of doing the above, you could have just put both in a single file and include the @media (prefers-color-scheme: dark) line in there directly, and this won’t require you to change your <head> at all. And of course you could have just used CSS variables and store the theme’s colors into different variables, use var(--variable-name) for each class in the styles, and finally have a different set up variable values for @media (prefers-color-scheme: dark) {}. But using the method of separating dark and light styles has the advantage of changing the themes for light or dark mode in the future with the chroma command and pipe it to the file directly, without having to edit the CSS file by hand.

# Applying syntax highlight CSS file only when it’s needed

Fetching syntax highlighting theme and putting it in your <head> means that every single page would have the syntax highlighting CSS code in the page, regardless of whether the page actually uses it. If you’d like to only include the syntax CSS files for pages that needs syntax highlighting, you can use a page parameter named something like highlight.

Here’s how it would work.

Set a highlight param in your global config file that is set to false by default
For each post or page in your content/ that needs syntax highlighting, include highlight: true in the frontmatter (assuming you’re using YAML).
In <head>, check whether the page’s highlight param is set to true, and only if it’s true, the CSS resource is loaded.

In your <head>, include this before fetching the CSS resource, and put {{ end }} after </style>:

{{- if .Params.highlight -}}
<!--Put the code that fetches your syntax highlight CSS here-->
{{- end -}}

This tells hugo to only load the resource and put the CSS in <style> if the page parameter highlight is set to true.

# Read more

Managing multiple emails for git across different computers

hedy.dev@protonmail.com (hedy) — Wed, 16 Jun 2021 23:50:00 +0000

As someone who code on multiple machines to work on different projects, I like to commit with different emails.

I don’t know how everyone else handle different emails in .gitconfig and track dotfiles in a git repo at the same time, but here’s the solution I’ve come up with.

First, I have a global ~/.gitconfig with the default user email and some other global settings (by global I mean same cross different computers I work on).

# ~/.gitconfig
[user]
name = Default Name
email = me@default.email

Then for each machine I have a ~/.gitconfig-local file which can override some settings just for that machine, such as email, signing key, editor, etc.

# ~/.gitconfig-local
[user]
email = me@special.email

Back in the global ~/.gitconfig, I have this snippet that tells git to also look for configuration in my ~/.gitconfig-local:

# ~/.gitconfig
[include]
path = ~/.gitconfig-local

Here, I can have ~/.gitconfig tracked in my dotfiles repo, but I do not have ~/.gitconfig-local tracked. This way, I can put anything I like specific to a particular machine in the ~/.gitconfig-local, as well as SMTP settings such as password, which you wouldn’t want to end up in a public git repo.

As to setting it up on a new machine, I have a setup script in my dotfiles repo that creates an empty ~/.gitconfig-local. I use this same method with fish configs – global config and a local config, you can have a look at them in my dotfiles repo on sourcehut.

On rants about gemini

hedy.dev@protonmail.com (hedy) — Tue, 15 Jun 2021 00:00:00 +0000

Recently there’ve been some discussions about how Gemini “doesn’t fix anything” on Lobste.rs:

As well as a few posts related to that on smol.pub:

I think that those comments on Lobsters can be summarized into these main points:

We don’t need a whole new protocol (and the corresponding new software) just because most of the web is gross
Gemtext doesn’t have tables, text styling, images, and forms. It’s too much of a significant price having to pay just to have a simpler document-focused version of the web
You simply can’t replace the web like this

Let’s take a look at each in detail.

# Replacing the web

[The web is] an organically grown mess of 25 years – but it will never be replaced by a dead-simple solution such as Gemini. (source)

And in response to that as mieum writes:

Almost all of these posts are obsessed with the same strawman: some supposed audacity of Gemini to attempt replacing the web. It’s hilarious that these authors (and commentors) have such poor reading comprehension.

As clearly as is written at the top on the Gemini homepage, people seem to forget that it neither wants nor tries to replace the web.

Gemini is not “the fix” for the web’s problems (or for gopher’s for that matter). It is just a habitat, really; a way to inhabit a virtual space with other people. What that is and means will always be overlooked from the point of view that assumes Gemini must be all or nothing at all; that it must be a challenger to the throne.

In my opinion, Gemini is just a virtual space to put your content and read other people’s work on. It’s not supposed to be “oh, the web sucks, let’s all just ditch the web switch over to this instead”. There are still many wonderful and peaceful things on the web. And if you’d prefer scrolling through feeds with personalized ads, or if you prefer super-responsive, sleek, modern web pages that have cute animations, then maybe Gemini might seem dull and that Gemini is not for you. Ultimately, (in the words of mieum) it’s a thriving ecosystem, and it doesn’t need to be anything more than that.

# Lack of functionality in comparison to HTML

In regards to gemtext limitations, we have to keep in mind that Gemini is a protocol. Gemtext is a markup language. You can serve whatever you like on Gemini – HTML, markdown, etc. And you can also view your HTML content over Gemini with a client that supports HTML. As far as I can tell, most features that gemtext lacks had been discussed in the mailing list before, all of which, I’m pretty sure, alternatives or workarounds were suggested. I think this comment by Alex summarises it well:

Everyone wants something added to Gemini but disagrees what that something is. Personally, I think it should be in-line images and footnotes, but if Gemini became more complex, it would lose many of the traits that make it interesting. Gemini is a technology that invites us not to try and improve or optimize it, but to accept it as it is and work around its limitations – it is intentionally austere, and this is a feature, not a bug. (source)

For me, I’m fine with not having inline images, footnotes, or maybe even syntax highlighting in preformatted text. But as to tables, yes, that could make it look better, and easier to copy contents, but it would lose its simplicity and ease of developing new software around it. If gemtext was to support a similar type of table syntax as markdown, for example, the table would look extremely broken for clients that do not support it. Unless it is put in a preformatted block, though in which case that wouldn’t solve the problem of horizontal scrolling in small screens.

In regards to inline links, sure, that could clear some clutter by removing the “[1]”, but support for this could lead to escaping characters in the syntax, and then escaping the characters that escape the characters, which adds layer upon layer of complexities, again, losing its simplicity.

For me personally, if gemtext supported tables, inline links, and maybe “—” dividers, it would make my life a tiny bit easier when creating content, (though not necessarily when developing my own client). But it’s not like you can’t do anything with gemtext. You’d just have to get used to it. Gemini strictly separates the roles of content and presentation, the author provides the content and the client can control the presentation in whatever style it likes.

# Do we need a whole new protocol?

For me personally, I like fresh starts. So sure, a new protocol, new ways to think about the internet, and some getting used to is a great idea. It might be a pain for some to set up mirrors of their web content, but it’s the experience and room to explore endless possibilities on a new medium that matters. Since you need new software, it’s a perfect opportunity to learn a new language and get your own stuff out there. It’s just the beginning, so there aren’t many “rulers” in this space, as opposed to the web with popular browsers like chrome.

At the end of the day, the fact that I create and browse content in Geminispace every now and then does not mean I’ve decided to not use the web at all, nor does it mean that all of the good content is in Geminispace instead of the web. Like mozz said on Station:

I’m not here because I hate the web, I’m here because I like Gemini. (source)

You don’t have to ditch the web to use Gemini. You get to choose what you write about, but you don’t get to choose the color of your headers, or the font size of your body paragraphs. You are free to use the web if you want that.

# Full list of references

How this site works

hedy.dev@protonmail.com (hedy) — Tue, 23 Feb 2021 00:00:00 +0000

2023 Update

I started writing this post on 2021, February 23 but I never completed it. So in 2023 I decided to finish up this outstanding post and get it done with. Surprisingly, the content did not change much other than moving from ~team to ~cafe (more on that later). I still use Hugo and write in Markdown. And I still publish to both WWW and Gemini.

Excuse the odd placing of this post, but otherwise, enjoy the read~

2024 March Update

I no longer host my website, gemini capsule and spartan content on tilde.cafe. As of writing, I’ve switched to srht.site for static HTTPS/gemini hosting with my own domain at home.hedy.dev.

I’m keeping this post (which as it turns out, I still never got to publish) as a historical record, whose information, other than the aforementioned differences, remains mostly accurate.

This is where my gemlog/blog lives. It is statically generated with Hugo and rsync-ed to my public_html and public_gemini directories for HTML and gemini on tilde.cafe respectively on build.

The site source is always linked at the footer, pointing to the sourcehut repo though the repo is also mirrored on github.

# tilde.cafe and the Tildeverse

[The Tildeverse is] a loose association of like-minded tilde communities. Tildes are pubnixes in the spirit of tilde.club, which was created in 2014 by Paul Ford

A Pubnix is a Public Access Unix System — in other words, a unix machine on the internet that provides access to other people on the internet — which started before WWW and even the public internet. Pubnixes you may have heard of SDF, Circumlunar.Space (yes, the very same one of the gemini homepage), and tilde.club.

~cmccabe has a Pubnix History Project for you to explore if you’re interested in learning more about pubnixes.

There are a lot of pubnixes that have joined the Tildeverse since the the ~club and ~team (which hosts the tildeverse website together with many services).

Most tildes have open registerations. Users are provided around 1 GB of disk space along with SSH access and are able to host their own static site with CGI under the main tilde domain, together with services like email, gemini/gopher hosting, pastbin, and more.

However, the true value of tildes lie not in the services they provide but the people and community. The tildeverse has an official IRC network, tilde.chat, which most tildes use for their main channel of communication. They also have a radio, a mastodon instance, gitea instance, among other services. The latter two from the above are both hosted by ~ben the owner of ~team.

I chose to host my personal website on tilde.cafe, a (relatively) newer tilde that runs on Debian with a smaller user base, and for the past two years most coding projects I had done were developed on ~Cafe’s server. It’s grown to become my second digital home on the internet ever since I started to use hedy at tilde.cafe for my primary email.

It was fun to work with ~cafe admins ~spider and ~jan6 in the early days, helping to set up and write the wiki and automated website builds. We used the #cafe channel on tilde.chat for our main chat.

Some time in 2021 or 2022, jan6 is no longer able to chat with us on #cafe in tilde.chat, and since spider became busy with work and other areas of life, we needed one more admin to take care of user support on tilde.cafe. I was promoted to join spider and jan6 as sudoers and have been helping with signups and sysadmin’ing since then.

I don’t plan to move off ~cafe to host my personal website, nor email in the foreseable future. Though when I have side-projects that required dedicated servers with subdomains, I will consider using my own server and domain. Until then, I remain eternally grateful to ~cafe and other tilde-owners for maintaining awesome communities and providing welcoming spaces online for strangers to come together and build cool stuff, with money from the admin’s own pockets.

If you’re someone who is recently discovering the tildeverse I highly recommend rawtext.club (though not a “tilde” but a very cool community of extremely interesting people), ~team (they have a welcoming chat — #team — easily second most active channel on tilde.chat), ~envs (they have an Akkoma instance, used by Rohan Kumar from seirdy.one whose articles you may have come across on the internet), and of course ~cafe (drop me an email if you registered after reading this and I’ll make sure to personally approve your sign-up ;P). Others may not agree on my choices so this is not at all to downplay the worth of other tildes: there’s almost no harm in having an account on every single one, though you can definitely meet some cool people!

# Software stack & workflows

No javascript is used. All content is written in Markdown and Gemtext, with the static HTMl output generated by Hugo. The styling is done with vanilla CSS, syntax highlighting provided by chroma.

When a new blog post is written, I would ensure both markdown and gemtext sources are done, then I would run make which uses Hugo and does some miscellaneous cleaning-up to produce HTMl files at ~/public_html and gemtext at ~/public_gemini. I then use a browser to access the folder locally to check that everything is working. When something needs updating, a single make is enough to rebuild the entire site.

Finally, I commit and push. If I wasn’t working on ~cafe directly I would next log into ~cafe, pull, and make from there. It’s guaranteed to perform the same from my home computer and on ~cafe given the same Hugo versions.

Since I ran make on ~cafe, the actual ~/public_* directories will be updated on the changes would be live! 🎉

~cafe web server handles the rest. (FTR: on WWW we use nginx and on Gemini we use Gemserv.)

# Hosting

The site and gemini capsule is to be accessed at hedy.tilde.cafe; it works on both protocols. You may be curious how we could have per-user vhosts on gemini — no, there is no built-in configuration option as of writing. This is done with a shell script that appends to config file a separate server configuration when a new user sign-up is approved, written by jan6.

The <user>.tilde.cafe vhost is also supported on spartan. I wrote the spartan server that cafe uses (spsrv) and it provides a config option to use per-user vhosts.

Hello world

hedy.dev@protonmail.com (hedy) — Fri, 05 Feb 2021 01:44:15 +0000

Hello hugo

hope it works!