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