the home site for me: also iteration 3 or 4 of my site
dunkirk.sh
1+++
2title = "Test Post"
3date = 2024-10-11
4slug = "test-post"
5description = "Testing out styling and features."
6
7[taxonomies]
8tags = ["meta"]
9
10[extra]
11has_toc = true
12+++
13
14This post is for me to just test out all the features and styling of the blog, and to
15make sure that if I change the CSS or anything I don't break any of it! This is also a
16sort of light style guide for blog posts in general.
17
18## Section Headers
19
20Sections headers (prefixed with `##` in markdown) are the main content separators for posts, and
21can be [linked to](#section-headers) directly. To link to them, the header's text needs to be
22*kebab-cased*, so the above would be `#section-headers`.
23
24### But what about sub-headers?
25
26I usually use `###` sub-headers to ask the question I think the reader is (or should be) asking at
27this point in the article. For example, if I just posted some code with an obvious error, I might
28follow that up with `### Wait, won't that crash?` or something similar. Using this approach lets
29me write posts in a conversational way, and helps me continually frame myself in the mind of the
30reader.
31
32### Table of Contents
33
34Section and sub-headers can be used to generate a table of contents at the start of the page. To
35enable this feature for a post, add the following to the page's frontmatter:
36
37> toml
38```toml
39[extra]
40has_toc = true
41```
42
43I don't like content that is nested more than 2 layers deep, so only `##` and `###` should be used
44to divide things up.
45
46## Embedding Code
47
48This is prominently a coding blog, so code will show up a lot. First off, a monospaced text block is
49denoted by wrapping the text in triple back-tick characters <code>```</code>.
50
51```
52┌──────────────────────────┐
53│ This text is monospaced. │
54│ This │
55│ text │
56│ is │
57│ monospaced. │
58└──────────────────────────┘
59```
60
61### Syntax Highlighting
62
63If you want syntax coloring, you put the name of the programming language immediately after the ticks.
64So writing this:
65
66~~~
67```rust
68fn main() {
69 println!("Hello, world!");
70}
71```
72~~~
73
74Will produce this:
75
76```rust
77fn main() {
78 println!("Hello, world!");
79}
80```
81
82### Code Block Title
83
84Sometimes it can help to give a header to a code block to signal what it represents. To do this, you put
85a single-line block quote immediately before the code block. So by prepending the following code with
86`> src/main.rs`, I can produce this:
87
88> src/main.rs
89```rust
90fn main() {
91 println!("This code is in main.rs!");
92}
93```
94
95This can be useful to explicitly state the programming language or format being used:
96
97> TOML
98```toml
99title = "Test Post"
100slug = "test-post"
101description = "Testing out styling and features."
102
103[taxonomies]
104tags = ["meta"]
105```
106
107### Inline Code
108
109As seen above, sometimes code items are mentioned in regular paragraphs, but you want to
110draw attention to them. To do this, you can wrap it in ` back-tick quotes. For
111example, if I wanted to mention Rust's `Vec<T>` type.
112
113```md
114`Vec<T>`
115```
116
117You can wrap a link around a code tag if you want to link to the docs, for example I could
118link to the [`Option<T>::take_if`](https://doc.rust-lang.org/std/option/enum.Option.html#method.take_if)
119method directly.
120
121```md
122[`Option<T>::take_if`](https://doc.rust-lang.org/std/option/enum.Option.html#method.take_if)
123```
124
125## Block Quotes
126
127I can display a quote by prepending multiple lines of text with `>` like so, which will
128wrap it in a `blockquote` tag:
129
130> "This text will appear italicized in a quote box!"
131
132### Reader Questions
133
134When displaying reader questions, I start the block quote with a bolded name, like so:
135
136> **SonicFan420x69 asks:**
137>
138> “What is your opinion of the inimitable video game character, Sonic the Hedgehog? Please
139> answer soon as it is a matter of life or death.”
140
141### Cited Quotations
142
143For when I want to have a citation, I can use the html `<cite>` tag after the quote text and it
144will prepend it with a nice `—` em dash.
145
146> "I don't know half of you half as well as I should like, and I like less than half of you half
147> as well as you deserve."
148>
149> <cite>Bilbo Baggins</cite>
150
151## Icons & Images
152
153They were shown in the previous section, but icons (provided by [Remix Icon](https://remixicon.com/)),
154can be used anywhere by inserting an `<i>` tag with the icon's class. These are useful for adding
155some detail and decorating to the pages, and is another way to break up text.
156
157## Embedding Media
158
159Images and videos are a great way to break up content and prevent text fatigue.
160
161### Images
162
163Images can be embedded using the usual markdown syntax:
164
165```md
166
167```
168
169
170
171When there are multiple paragraphs of text in a row (usually 3-4), and nothing else to break
172them up, images can be interspersed to help prevent text-wall fatique.
173
174You can also add captions to images:
175
176<figure>
177 <img src="https://img.itch.zone/aW1hZ2UvNTU2NDU0LzI5MTYzNzkucG5n/original/8LIdCb.png" alt="NOISE1 screenshot">
178 <figcaption>
179 NOISE1 is a dark sci-fi hacker-typing stealth game.
180 </figcaption>
181</figure>
182
183But there is no way to do this in markdown so you have to use the `<figure>` tag like so:
184
185```html
186<figure>
187 <img src="/path/to/image.png" alt="Alt text goes here.">
188 <figcaption>Caption text goes here.</figcaption>
189</figure>
190```
191
192### Videos
193
194To embed a video, you use the `youtube` shortcode e.g.
195
196> post.md
197```md
198{{/* youtube(id="kiWvNwuBbEE") */}}
199```
200
201You can also add the `autoplay=true` flag to make the video autoplay.
202
203{{ youtube(id="NodwjZF7uZw") }}
204
205The shortcode is processed into an iframe which looks like this:
206
207> post.html
208```html
209{{ youtube(id="kiWvNwuBbEE") }}
210```
211
212## Miscellaneous
213
214You can also create `<hr>` horizontal rule tags using `---` in markdown, like so:
215
216---
217
218But these should be used sparingly, if at all.