the home site for me: also iteration 3 or 4 of my site
feat: add blog
+279
+263
content/blog/2024-10-11_example_post.md
+263
content/blog/2024-10-11_example_post.md
···
1
+
+++
2
+
title = "Test Post"
3
+
date = 2024-10-11
4
+
slug = "test-post"
5
+
description = "Testing out styling and features."
6
+
7
+
[taxonomies]
8
+
tags = ["meta"]
9
+
10
+
[extra]
11
+
has_toc = true
12
+
+++
13
+
14
+
This post is for me to just test out all the features and styling of the blog, and to
15
+
make sure that if I change the CSS or anything I don't break any of it! This is also a
16
+
sort of light style guide for blog posts in general.
17
+
18
+
<!-- more -->
19
+
20
+
First off, this paragraph is after the `<!-- more -->` cutoff, which means that it *should not*
21
+
appear in thumbnails linking to this post from elsewhere on the site.
22
+
23
+
## Section Headers
24
+
25
+
Sections headers (prefixed with `##` in markdown) are the main content separators for posts, and
26
+
can be [linked to](#section-headers) directly. To link to them, the header's text needs to be
27
+
*kebab-cased*, so the above would be `#section-headers`.
28
+
29
+
### But what about sub-headers?
30
+
31
+
I usually use `###` sub-headers to ask the question I think the reader is (or should be) asking at
32
+
this point in the article. For example, if I just posted some code with an obvious error, I might
33
+
follow that up with `### Wait, won't that crash?` or something similar. Using this approach lets
34
+
me write posts in a conversational way, and helps me continually frame myself in the mind of the
35
+
reader.
36
+
37
+
### Table of Contents
38
+
39
+
Section and sub-headers can be used to generate a table of contents at the start of the page. To
40
+
enable this feature for a post, add the following to the page's frontmatter:
41
+
42
+
> toml
43
+
```toml
44
+
[extra]
45
+
has_toc = true
46
+
```
47
+
48
+
I don't like content that is nested more than 2 layers deep, so only `##` and `###` should be used
49
+
to divide things up.
50
+
51
+
## Embedding Code
52
+
53
+
This is prominently a coding blog, so code will show up a lot. First off, a monospaced text block is
54
+
denoted by wrapping the text in triple back-tick characters <code>```</code>.
55
+
56
+
```
57
+
┌──────────────────────────┐
58
+
│ This text is monospaced. │
59
+
│ This │
60
+
│ text │
61
+
│ is │
62
+
│ monospaced. │
63
+
└──────────────────────────┘
64
+
```
65
+
66
+
### Syntax Highlighting
67
+
68
+
If you want syntax coloring, you put the name of the programming language immediately after the ticks.
69
+
So writing this:
70
+
71
+
~~~
72
+
```rust
73
+
fn main() {
74
+
println!("Hello, world!");
75
+
}
76
+
```
77
+
~~~
78
+
79
+
Will produce this:
80
+
81
+
```rust
82
+
fn main() {
83
+
println!("Hello, world!");
84
+
}
85
+
```
86
+
87
+
### Code Block Title
88
+
89
+
Sometimes it can help to give a header to a code block to signal what it represents. To do this, you put
90
+
a single-line block quote immediately before the code block. So by prepending the following code with
91
+
`> src/main.rs`, I can produce this:
92
+
93
+
> src/main.rs
94
+
```rust
95
+
fn main() {
96
+
println!("This code is in main.rs!");
97
+
}
98
+
```
99
+
100
+
This can be useful to explicitly state the programming language or format being used:
101
+
102
+
> TOML
103
+
```toml
104
+
title = "Test Post"
105
+
slug = "test-post"
106
+
description = "Testing out styling and features."
107
+
108
+
[taxonomies]
109
+
tags = ["meta"]
110
+
```
111
+
112
+
### Inline Code
113
+
114
+
As seen above, sometimes code items are mentioned in regular paragraphs, but you want to
115
+
draw attention to them. To do this, you can wrap it in ` back-tick quotes. For
116
+
example, if I wanted to mention Rust's `Vec<T>` type.
117
+
118
+
```md
119
+
`Vec<T>`
120
+
```
121
+
122
+
You can wrap a link around a code tag if you want to link to the docs, for example I could
123
+
link to the [`Option<T>::take_if`](https://doc.rust-lang.org/std/option/enum.Option.html#method.take_if)
124
+
method directly.
125
+
126
+
```md
127
+
[`Option<T>::take_if`](https://doc.rust-lang.org/std/option/enum.Option.html#method.take_if)
128
+
```
129
+
130
+
## Block Quotes
131
+
132
+
I can display a quote by prepending multiple lines of text with `>` like so, which will
133
+
wrap it in a `blockquote` tag:
134
+
135
+
> "This text will appear italicized in a quote box!"
136
+
137
+
### Reader Questions
138
+
139
+
When displaying reader questions, I start the block quote with a bolded name, like so:
140
+
141
+
> **SonicFan420x69 asks:**
142
+
>
143
+
> “What is your opinion of the inimitable video game character, Sonic the Hedgehog? Please
144
+
> answer soon as it is a matter of life or death.”
145
+
146
+
### Cited Quotations
147
+
148
+
For when I want to have a citation, I can use the html `<cite>` tag after the quote text and it
149
+
will prepend it with a nice `—` em dash.
150
+
151
+
> "I don't know half of you half as well as I should like, and I like less than half of you half
152
+
> as well as you deserve."
153
+
>
154
+
> <cite>Bilbo Baggins</cite>
155
+
156
+
### Callouts
157
+
158
+
Sometimes I want to draw the user's attention to a useful piece of information. If I start a
159
+
blockquote with an [`<i> icon`](#icons-images), it will style it as a callout. For example,
160
+
I could make a little indented to-do list by starting a quote with this:
161
+
162
+
```html
163
+
> <i class="ri-checkbox-multiple-fill"></i> **To Do**
164
+
```
165
+
166
+
Which will produce this:
167
+
168
+
> <i class="ri-checkbox-multiple-fill"></i> **To Do**
169
+
>
170
+
> - <i class="ri-checkbox-line"></i> Section Headers
171
+
> - <i class="ri-checkbox-line"></i> Syntax Highlighting
172
+
> - <i class="ri-checkbox-line"></i> Block Quotes
173
+
> - <i class="ri-checkbox-blank-line"></i> Images & Icons
174
+
175
+
### Warnings
176
+
177
+
If the icon class is `ri-error-warning-line`, the callout will be colored red:
178
+
179
+
> <i class="ri-error-warning-line"></i> **Warning!**
180
+
>
181
+
> Here is something you should be warned about! There's even a big red
182
+
> bubble here so you know it's serious. Make sure you don't miss it, or
183
+
> the consequences could be dire...
184
+
185
+
If the icon class is `ri-lightbulb-line`, then the callout will be colored blue.
186
+
187
+
> <i class="ri-lightbulb-line"></i> **Did you know?**
188
+
>
189
+
> This isn't a warning, but I wanted to draw your attention to something cool! Did you know
190
+
> I take [reader questions](/ask), and will answer them on this blog? Now you know!
191
+
192
+
These add more colors—and therefore noise—to the page and should be used sparingly.
193
+
The warning callout specifically is to alert readers to something particularly important, such
194
+
as unsafe code or something they shouldn't do.
195
+
196
+
## Icons & Images
197
+
198
+
They were shown in the previous section, but icons (provided by [Remix Icon](https://remixicon.com/)),
199
+
can be used anywhere by inserting an `<i>` tag with the icon's class. These are useful for adding
200
+
some detail and decorating to the pages, and is another way to break up text.
201
+
202
+
### Icon Tags
203
+
204
+
For example, we could check items off a to-do list as the reader progresses in a tutorial:
205
+
206
+
- <i class="ri-checkbox-line"></i> Wake up
207
+
- <i class="ri-checkbox-line"></i> Eat breakfast
208
+
- <i class="ri-checkbox-line"></i> Finish this post
209
+
- <i class="ri-checkbox-blank-line"></i> ???
210
+
- <i class="ri-checkbox-blank-line"></i> Profit!
211
+
212
+
## Embedding Media
213
+
214
+
Images and videos are a great way to break up content and prevent text fatigue.
215
+
216
+
### Images
217
+
218
+
Images can be embedded using the usual markdown syntax:
219
+
220
+
```md
221
+
222
+
```
223
+
224
+
225
+
226
+
When there are multiple paragraphs of text in a row (usually 3-4), and nothing else to break
227
+
them up, images can be interspersed to help prevent text-wall fatique.
228
+
229
+
You can also add captions to images:
230
+
231
+
<figure>
232
+
<img src="https://img.itch.zone/aW1hZ2UvNTU2NDU0LzI5MTYzNzkucG5n/original/8LIdCb.png" alt="NOISE1 screenshot">
233
+
<figcaption>
234
+
NOISE1 is a dark sci-fi hacker-typing stealth game.
235
+
</figcaption>
236
+
</figure>
237
+
238
+
But there is no way to do this in markdown so you have to use the `<figure>` tag like so:
239
+
240
+
```html
241
+
<figure>
242
+
<img src="/path/to/image.png" alt="Alt text goes here.">
243
+
<figcaption>Caption text goes here.</figcaption>
244
+
</figure>
245
+
```
246
+
247
+
### Videos
248
+
249
+
To embed a video, you use whatever embed tag works. For example, YouTube provides an `<iframe>` tag for
250
+
videos that you can use to embed into the page:
251
+
252
+
<iframe src="https://www.youtube.com/embed/kiWvNwuBbEE" title="Ikenfell Launch Trailer" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
253
+
254
+
Do not use a `width` or `height` when doing this. The video should always be the full width of the page,
255
+
and the height will be auto-calculated based on a 16:9 aspect ratio.
256
+
257
+
## Miscellaneous
258
+
259
+
You can also create `<hr>` horizontal rule tags using `---` in markdown, like so:
260
+
261
+
---
262
+
263
+
But these should be used sparingly, if at all.
+6
content/blog/_index.md
+6
content/blog/_index.md
+10
templates/blog.html
+10
templates/blog.html
···
1
+
{% extends "base.html" %} {% block content %}
2
+
<h1 class="title">{{ section.title }}</h1>
3
+
<ul>
4
+
<!-- If you are using pagination, section.pages will be empty.
5
+
You need to use the paginator object -->
6
+
{% for page in section.pages %}
7
+
<li><a href="{{ page.permalink | safe }}">{{ page.title }}</a></li>
8
+
{% endfor %}
9
+
</ul>
10
+
{% endblock content %}