Skip to content

Commit d654a34

Browse files
iasonliuiasonliu
authored
Merge pull request #7 from 42devops/fix/annotations-layout-spacing
fix: optimize annotations spacing and hero layout
2 parents 1592bcf + 083858d commit d654a34

3 files changed

Lines changed: 62 additions & 40 deletions

File tree

‎_posts/2026-07-23-neat-annotations-guide.md‎

Lines changed: 34 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -8,40 +8,50 @@ comments: true
88

99
This blog is now powered by **[neat-annotations](https://github.com/syabro/neat-annotations)** — a zero-JS CSS library for hand-drawn arrows, handwritten labels, and inline highlights.
1010

11-
Here is a quick guide on how to annotate text in your Markdown posts using simple HTML markup!
11+
Here is a quick reference guide on how to annotate text in your Markdown articles!
1212

13-
## Directional Arrows
13+
## Inline Highlights (Recommended for body text)
1414

15-
You can point handwritten arrows from 8 different directions:
15+
When annotating inline body text, use **highlight-only** markers without floating notes or arrows. They render cleanly without disrupting line height or overlapping adjacent text:
1616

17-
- **North (`ann-n`)**: <span class="ann ann-n ann-amber" data-note="Points up">Target Text</span> (label sits below)
18-
- **South (`ann-s`)**: <span class="ann ann-s ann-blue" data-note="Points down">Target Text</span> (label sits above)
19-
- **East (`ann-e`)**: <span class="ann ann-e ann-green" data-note="Points right">Target Text</span>
20-
- **West (`ann-w`)**: <span class="ann ann-w ann-purple" data-note="Points left">Target Text</span>
21-
- **North-West (`ann-nw`)**: <span class="ann ann-nw ann-red" data-note="Top-left corner">Target Text</span>
17+
<div style="background: var(--bg-subtle); border-radius: var(--radius-md); padding: 1.5rem 1.75rem; margin: 1.5rem 0; border: 1px solid var(--border-color);">
18+
You can mark <span class="ann ann-amber">important words</span>, highlight <span class="ann ann-blue">key metrics</span>, or emphasize <span class="ann ann-green">critical commands</span> seamlessly inside any paragraph.
19+
</div>
2220

23-
## Color Palette
21+
## Code & Specification Showcase ("In the Wild")
2422

25-
`neat-annotations` comes with 6 built-in color styles:
23+
When you want to point arrows at code tokens, parameters, or specifications, give lines generous line-height (`3.4em`) so hand-drawn labels sit cleanly around the target text:
2624

27-
1. **Amber**: <span class="ann ann-amber ann-n" data-note="Amber note">Highlight text</span>
28-
2. **Blue**: <span class="ann ann-blue ann-s" data-note="Blue note">Highlight text</span>
29-
3. **Green**: <span class="ann ann-green ann-n" data-note="Green note">Highlight text</span>
30-
4. **Red**: <span class="ann ann-red ann-s" data-note="Red note">Highlight text</span>
31-
5. **Purple**: <span class="ann ann-purple ann-n" data-note="Purple note">Highlight text</span>
32-
6. **Rainbow**: <span class="ann ann-rainbow ann-s" data-note="Animated hues!">Highlight text</span>
25+
<div class="ann-showcase-card">
26+
<div style="color: var(--text-light); font-size: 0.8rem; line-height: 1; margin-bottom: 3.8rem; display: flex; align-items: center; gap: 0.5rem;">
27+
<span style="color: #ff5f56;">●</span><span style="color: #ffbd2e;">●</span><span style="color: #27c93f;">●</span>
28+
<span style="margin-left: 0.5rem;">docs/specs/cli.md</span>
29+
</div>
3330

34-
## Highlight Only (No Label)
31+
<div style="margin-bottom: 2.5rem;">
32+
- <span class="ann ann-amber ann-s" data-note="open task">[ ]</span>
33+
<span class="ann ann-blue ann-s" data-note="stable ID">CLI-042</span> Add export command
34+
<span class="ann ann-green ann-se" data-note="tag">#cli</span>
35+
<span class="ann ann-red ann-sw" data-note="priority">!high</span>
36+
<span class="ann ann-purple ann-nw" data-note="custom field">@blocked_by:CLI-041</span>
37+
</div>
3538

36-
Omit `data-note` and direction classes to create a simple handwritten marker highlight:
39+
<div style="margin-top: 2rem;">
40+
Write task output as <span class="ann ann-n ann-amber" data-note="description">JSON</span> for scripts and agents
41+
</div>
42+
</div>
3743

38-
You can mark <span class="ann ann-amber">important words</span> or <span class="ann ann-green">key metrics</span> seamlessly inline without arrows or notes.
44+
## Markdown Markup Syntax
3945

40-
## Markdown Example
46+
To add annotations to your Markdown posts, simply wrap your target text in a `<span>` tag:
4147

4248
```html
43-
<!-- Example annotation in markdown -->
44-
The system updates <span class="ann ann-n ann-amber" data-note="zero downtime">in real time</span>.
45-
```
49+
<!-- Highlight only (no arrow) -->
50+
<span class="ann ann-amber">important note</span>
51+
52+
<!-- Arrow pointing South with handwritten label -->
53+
<span class="ann ann-s ann-blue" data-note="stable ID">CLI-042</span>
4654

47-
Try using annotations in your next technical post to highlight key parameters, architecture points, or code snippets!
55+
<!-- Arrow pointing North with handwritten label -->
56+
<span class="ann ann-n ann-amber" data-note="description">JSON</span>
57+
```

‎css/screen.css‎

Lines changed: 23 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -173,32 +173,48 @@ body {
173173

174174
/* Hero Intro Banner */
175175
.hero-banner {
176-
padding: 1.75rem 0 2.25rem 0;
176+
padding: 2rem 0 3rem 0;
177177
margin-bottom: 2.5rem;
178178
}
179179

180180
.hero-title {
181-
font-size: 2rem;
181+
font-size: 2.2rem;
182182
font-weight: 800;
183-
line-height: 1.25;
183+
line-height: 1.8;
184184
letter-spacing: -0.03em;
185185
color: var(--text-main);
186-
margin-bottom: 0.75rem;
186+
margin-bottom: 2.5rem;
187187
}
188188

189189
.hero-subtitle {
190190
font-size: 1.05rem;
191191
color: var(--text-muted);
192-
max-width: 620px;
193-
line-height: 1.6;
192+
max-width: 650px;
193+
line-height: 2.2;
194+
}
195+
196+
/* Annotation Showcase Box */
197+
.ann-showcase-card {
198+
background: var(--bg-card);
199+
border: 1px solid var(--border-color);
200+
border-radius: var(--radius-lg);
201+
padding: 3.5rem 2.5rem;
202+
margin: 2.5rem 0;
203+
box-shadow: var(--shadow-md);
204+
font-family: var(--font-mono);
205+
font-size: 0.95rem;
206+
line-height: 3.4;
207+
overflow-x: auto;
194208
}
195209

196210
/* Section Headings */
197211
.section-header {
198212
display: flex;
199213
align-items: center;
200214
justify-content: space-between;
201-
margin-bottom: 1.25rem;
215+
margin-top: 1.5rem;
216+
margin-bottom: 1.75rem;
217+
padding-top: 0.5rem;
202218
}
203219

204220
.section-title {

‎index.html‎

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,13 @@ <h1 class="hero-title">
99
&amp; <span class="ann ann-n ann-amber" data-note="The Ultimate Answer">42</span> Engineering Notes
1010
</h1>
1111
<p class="hero-subtitle">
12-
Exploring <span class="ann ann-s ann-blue" data-note="Cloud Native">Kubernetes</span>, automation, <span class="ann ann-nw ann-purple" data-note="System Design">Infrastructure</span>, and algorithms.
12+
Exploring <span class="ann ann-blue">Kubernetes</span>, automation, <span class="ann ann-purple">Infrastructure</span>, and algorithms.
1313
</p>
1414
</section>
1515

16-
<section id="articles" style="margin-bottom: 3.5rem;">
16+
<section id="articles" style="margin-bottom: 3rem;">
1717
<div class="section-header">
18-
<h2 class="section-title">
19-
<span class="ann ann-n ann-green" data-note="Latest Posts">Articles</span>
20-
</h2>
18+
<h2 class="section-title">Articles</h2>
2119
</div>
2220

2321
<div class="filter-bar" id="category-filters">
@@ -54,11 +52,9 @@ <h3 class="post-card-title">{{ post.title }}</h3>
5452
</div>
5553
</section>
5654

57-
<section id="projects" style="margin-bottom: 3.5rem;">
55+
<section id="projects" style="margin-bottom: 3rem;">
5856
<div class="section-header">
59-
<h2 class="section-title">
60-
<span class="ann ann-n ann-rainbow" data-note="Open Source">Featured Projects</span>
61-
</h2>
57+
<h2 class="section-title">Featured Projects</h2>
6258
</div>
6359

6460
<div class="projects-grid">

0 commit comments

Comments
 (0)