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