Asset Embedding for Blogs

Blog posts use a central assets folder organized by post slug. This differs from docs where assets are relative to each file.

For the general [[path]] syntax, see Markdown Asset Embedding.

Assets Folder Structure

All blog assets are stored in a central assets/ folder with subfolders matching each post's slug:

blog/
├── 2024-01-15-hello-world.md
├── 2024-02-01-new-feature.md
├── 2024-02-15-tips-and-tricks.md
└── assets/
    ├── 2024-01-15-hello-world/
    │   ├── cover.jpg
    │   ├── diagram.png
    │   └── code.py
    ├── 2024-02-01-new-feature/
    │   └── screenshot.png
    └── 2024-02-15-tips-and-tricks/
        └── example.js

Path Resolution

In blogs, asset paths resolve to the post's subfolder in assets/:

blog/
├── 2024-01-15-hello-world.md   ← [[diagram.png]]
└── assets/
    └── 2024-01-15-hello-world/
        └── diagram.png          ← Resolved here

Example:

<!-- In 2024-01-15-hello-world.md -->
```python
[[code.py]]


Resolves to: `blog/assets/2024-01-15-hello-world/code.py`

## No Relative Paths Needed

Unlike docs, you don't need `./` or folder paths:

```markdown
<!-- Docs style (NOT used in blogs) -->
[[./assets/diagram.png]]

<!-- Blog style (correct) -->
[[diagram.png]]

The system automatically resolves to the correct subfolder based on the post filename.

Creating Asset Folders

When creating a new post, create a matching asset folder:

Create post: 2024-03-01-my-new-post.md
Create folder: assets/2024-03-01-my-new-post/
Add assets to the folder
Reference in post: \[[myfile.png]]

Code Files

Embed code inside fenced blocks:

```python
[[example.py]]
```

The content of assets/<post-slug>/example.py replaces [[example.py]].

Images

For images, use standard markdown (not [[path]]):

![Cover image](./assets/2024-01-15-hello-world/cover.jpg)

Or use the frontmatter image field for cover images:

---
image: /images/blog/cover.jpg
---

Organizing Assets

By Type

assets/
└── 2024-01-15-hello-world/
    ├── code/
    │   ├── example.py
    │   └── config.yaml
    └── images/
        ├── screenshot.png
        └── diagram.svg

When using subfolders, include the path:

[[code/example.py]]
[[images/diagram.svg]]

Comparison: Docs vs Blogs

Feature	Docs	Blogs
Asset location	Next to file	Central `assets/` folder
Path syntax	`\[[./assets/file.py]]`	`\[[file.py]]`
Organization	Per-folder assets	Per-post subfolders
Relative paths	Required	Not needed

Best Practices

Match folder to filename - 2024-01-15-post.md → assets/2024-01-15-post/
Use descriptive names - architecture-diagram.png not img1.png
Organize large posts - Use subfolders for many assets
Keep assets minimal - Only include what's needed
Optimize images - Compress before adding