Jafner.net/sites/Jafner.dev/README.md

# Running local dev server
1. Ensure theme submodule is loaded: `git submodule init && git submodule update`
2. Run the server with `hugo server --noHTTPCache --ignoreCache --disableFastRender --buildDrafts`

## Including Images in Content
*Good old-fashioned `![](image.png)` markdown image embedding works just fine.*

1. Place the image file beside the content in the folder (called a ["page bundle"](https://gohugo.io/content-management/page-bundles/)).
2. For a Featured Image, use the line `featured_image = "image.jpg"` in the frontmatter.
3. For an inline image, use `{{< image src="image.jpg" >}}`

> Note: The working directory for relative resource locations uses the name of the content file as the current location. E.g. referencing the image `./myimage.jpg` or `./myimage.jpg` from inside the `/content/projects/myproject.md` content file, would look for those images at `/content/projects/myproject/myimage.jpg`. 

## Add a Table of Contents
- To include a table of contents at the beginning of a page, add the flag `toc = true` to the frontmatter. 
- To insert a table of contents inline with the text, use the `{{% toc %}}` shortcode.
- Tables of contents are configured under the `[markup]` configuration node in [`config.toml`](/config.toml).

## Create a New Homelab or Project Article
Use hugo's `hugo new content` command with the path (relative to root) to the content page for the new article. 

Examples:
- `hugo new content content/projects/my-new-project.md` This will create a new draft page with the title and date set smartly, as well as `draft = true`
- `hugo new content content/projects/my-new-project/index.md` This will create a new draft page inside a page bundle, creating the bundle directory if needed. 

## Set non-default `og:image` image for embedders
To set the image that is used when other sites or services embed a link (e.g. Discord), we use the `ogimage` page param in the frontmatter. The value is the path to the desired image relative to the `static` directory. 

Examples:
- Unset `ogimage` tag will fall back to [`/static/img/logo.png`](/static/img/logo.png).
- `ogimage = 'img/mobilebanner.png'` will use `/static/img/mobilebanner.png`.

This is separate from any image content visible on the site itself, which makes it useful for preserving the cleanliness of the reading experience.

## Generate article images with ImageMagick
Assign the text to use for the article image to the `LOGOTEXT` variable. E.g. `LOGOTEXT="Jafner.dev"`

```bash
LOGOTEXT="Jafner.dev"
convert -size 1200x630 xc:#1b1c1d -pointsize 110 -font "Noto-Sans-Mono-Regular" \
   -fill #A9A9B3 -draw "text 50,360 '>$ ~/$LOGOTEXT'"\
   -fill #FE5186 -gravity East -draw "text 50,0 '█'"\
   $LOGOTEXT.logo.png
```

And that will generate an image like:

![](jafner.dev.logo.png)

It can be a little finicky to make the text *look right*, especially getting the left-right spacing down. Use the following parameters to make changes:

- `xc:#1b1c1d` sets the background color to the provided hex code.
- `-pointsize 128` sets the font size of the text.
- The first `-font @Inter.ttf` sets the font to [Inter](https://fonts.google.com/specimen/Inter), the preferred font for the site. 
- The first `-fill #A9A9B3` sets the color for the text part of the logo.
- The first `-draw "text 50,360 '>$ ~/$LOGOTEXT'"` draws the `>$ ~/` part of the logo, then uses the `$LOGOTEXT` variable for the proceeding text. The `text 50,360` describes the X,Y offset in pixels from the top-left of the image to begin drawing the text. 
- The second `-font "Noto-Sans-Mono-Regular"` sets the font we need to use for Unicode character support. See the list of available fonts with `convert -list font | less`. If we don't need the cursor block, this entire line can be omitted.
- The second `-fill #FE5186` sets the color of the [cursor block](https://www.compart.com/en/unicode/U+2588).
- `-gravity East` sets the draw orientation to the middle of the right side of the frame. 
- The second `-draw "text 50,0 '█'"` draws the unicode cursor block character 50 pixels X-offset (from the middle-right) 

Hex codes:
- Pink cursor block: #FE5186
- Dark grey header background: #1A1B1C
- Light grey header logo text: #A9A9B2

# Organizing Content
When creating new content, we gotta keep in mind a few of the systems that are dependent on organizational consistency.

1. Use `slug = 'mypage'` to set the name that will be used in the URL, and in the dynamic logo at the top-left.
   1. For `homelab` articles, this will be prepended with `/homelab/` already, so don't be redundant. E.g. don't use `slug = 'homelab-tour'`, use `slug = 'tour'`. The former will render as `/homelab/homelab-tour/` and the latter will render as `/homelab/tour/`
2. Isn't `/homelab/` a type of `/projects/` ? Yes. But it's such a huge project that it has earned its own category.
3. Titles should be either like `Homelab Tour: Reviewing the what, how, and why of my lab`, or `Esports-grade Overwatch 2 on Linux`. That is, either a very short title with an expounding subtitle, or a sufficiently self-descriptive title. 
   1. Use a colon to separate subtitle.
Minor polish 2024-06-28 10:23:03 -07:00			`# Running local dev server`
			1. Ensure theme submodule is loaded: `git submodule init && git submodule update`
Publish Homelab Tour Series Intro Fix intermittently broken article/project list rendering, implement table of contents shortcode, implement css snippet to reduce underline-fatigue for table of contents, remove filler article files, generate static files. 2024-06-28 17:25:59 -07:00			2. Run the server with `hugo server --noHTTPCache --ignoreCache --disableFastRender --buildDrafts`
Minor polish 2024-06-28 10:23:03 -07:00
			`## Including Images in Content`
Publish Homelab Tour Series Intro Fix intermittently broken article/project list rendering, implement table of contents shortcode, implement css snippet to reduce underline-fatigue for table of contents, remove filler article files, generate static files. 2024-06-28 17:25:59 -07:00			Good old-fashioned `![](image.png)` markdown image embedding works just fine.

Update docs for including images 2024-06-29 13:12:23 -07:00			`1. Place the image file beside the content in the folder (called a ["page bundle"](https://gohugo.io/content-management/page-bundles/)).`
			2. For a Featured Image, use the line `featured_image = "image.jpg"` in the frontmatter.
			3. For an inline image, use `{{< image src="image.jpg" >}}`
Minor polish 2024-06-28 10:23:03 -07:00
Update docs for including images 2024-06-29 13:12:23 -07:00			> Note: The working directory for relative resource locations uses the name of the content file as the current location. E.g. referencing the image `./myimage.jpg` or `./myimage.jpg` from inside the `/content/projects/myproject.md` content file, would look for those images at `/content/projects/myproject/myimage.jpg`.
Publish Homelab Tour Series Intro Fix intermittently broken article/project list rendering, implement table of contents shortcode, implement css snippet to reduce underline-fatigue for table of contents, remove filler article files, generate static files. 2024-06-28 17:25:59 -07:00
			`## Add a Table of Contents`
			- To include a table of contents at the beginning of a page, add the flag `toc = true` to the frontmatter.
			- To insert a table of contents inline with the text, use the `{{% toc %}}` shortcode.
			- Tables of contents are configured under the `[markup]` configuration node in [`config.toml`](/config.toml).

Document creating content, setting og:image tags, and generating article images Add section for creating content articles with hugo cli Add section for setting non-default `og:image` header tags Add section for generating article images with ImageMagick Add section for organizing content pages 2024-06-29 23:36:29 -07:00			`## Create a New Homelab or Project Article`
			Use hugo's `hugo new content` command with the path (relative to root) to the content page for the new article.

			`Examples:`
			- `hugo new content content/projects/my-new-project.md` This will create a new draft page with the title and date set smartly, as well as `draft = true`
			- `hugo new content content/projects/my-new-project/index.md` This will create a new draft page inside a page bundle, creating the bundle directory if needed.

			## Set non-default `og:image` image for embedders
			To set the image that is used when other sites or services embed a link (e.g. Discord), we use the `ogimage` page param in the frontmatter. The value is the path to the desired image relative to the `static` directory.

			`Examples:`
			- Unset `ogimage` tag will fall back to [`/static/img/logo.png`](/static/img/logo.png).
			- `ogimage = 'img/mobilebanner.png'` will use `/static/img/mobilebanner.png`.

			`This is separate from any image content visible on the site itself, which makes it useful for preserving the cleanliness of the reading experience.`

			`## Generate article images with ImageMagick`
			Assign the text to use for the article image to the `LOGOTEXT` variable. E.g. `LOGOTEXT="Jafner.dev"`

			```bash
			`LOGOTEXT="Jafner.dev"`
Update og image generator command to use 1200x630 instead of 1200x627 2024-07-05 12:13:23 -07:00			`convert -size 1200x630 xc:#1b1c1d -pointsize 110 -font "Noto-Sans-Mono-Regular" \`
Switch font used for embed images to Noto Sans Mono Regular to match site logo 2024-06-30 01:45:20 -07:00			`-fill #A9A9B3 -draw "text 50,360 '>$ ~/$LOGOTEXT'"\`
			`-fill #FE5186 -gravity East -draw "text 50,0 '█'"\`
			`$LOGOTEXT.logo.png`
Document creating content, setting og:image tags, and generating article images Add section for creating content articles with hugo cli Add section for setting non-default `og:image` header tags Add section for generating article images with ImageMagick Add section for organizing content pages 2024-06-29 23:36:29 -07:00			```

			`And that will generate an image like:`

			`![](jafner.dev.logo.png)`

			`It can be a little finicky to make the text look right, especially getting the left-right spacing down. Use the following parameters to make changes:`

			- `xc:#1b1c1d` sets the background color to the provided hex code.
			- `-pointsize 128` sets the font size of the text.
			- The first `-font @Inter.ttf` sets the font to [Inter](https://fonts.google.com/specimen/Inter), the preferred font for the site.
			- The first `-fill #A9A9B3` sets the color for the text part of the logo.
			- The first `-draw "text 50,360 '>$ ~/$LOGOTEXT'"` draws the `>$ ~/` part of the logo, then uses the `$LOGOTEXT` variable for the proceeding text. The `text 50,360` describes the X,Y offset in pixels from the top-left of the image to begin drawing the text.
			- The second `-font "Noto-Sans-Mono-Regular"` sets the font we need to use for Unicode character support. See the list of available fonts with `convert -list font \| less`. If we don't need the cursor block, this entire line can be omitted.
			- The second `-fill #FE5186` sets the color of the [cursor block](https://www.compart.com/en/unicode/U+2588).
			- `-gravity East` sets the draw orientation to the middle of the right side of the frame.
			- The second `-draw "text 50,0 '█'"` draws the unicode cursor block character 50 pixels X-offset (from the middle-right)

			`Hex codes:`
			`- Pink cursor block: #FE5186`
			`- Dark grey header background: #1A1B1C`
			`- Light grey header logo text: #A9A9B2`

			`# Organizing Content`
			`When creating new content, we gotta keep in mind a few of the systems that are dependent on organizational consistency.`

			1. Use `slug = 'mypage'` to set the name that will be used in the URL, and in the dynamic logo at the top-left.
			1. For `homelab` articles, this will be prepended with `/homelab/` already, so don't be redundant. E.g. don't use `slug = 'homelab-tour'`, use `slug = 'tour'`. The former will render as `/homelab/homelab-tour/` and the latter will render as `/homelab/tour/`
			2. Isn't `/homelab/` a type of `/projects/` ? Yes. But it's such a huge project that it has earned its own category.
			3. Titles should be either like `Homelab Tour: Reviewing the what, how, and why of my lab`, or `Esports-grade Overwatch 2 on Linux`. That is, either a very short title with an expounding subtitle, or a sufficiently self-descriptive title.
			`1. Use a colon to separate subtitle.`