notes — RSS Feedhttps://notes.druchan.com/notes Sat, 18 Jan 2025 12:00:00 +0530 Caching https://blog.vaak.com/caching https://blog.vaak.com/caching vāk caches builds to speed up your workflow. Unchanged files don't need re-building, so subsequent builds are faster.

How it works

Build cache data is stored in a .cache file in your project directory. When you run vāk build, only modified posts and templates are processed.

Rebuilding everything

To force a complete rebuild:

vāk rebuild

This removes the .cache file and rebuilds the entire site.

Common scenarios

Deleted a post but its HTML file still exists?

This happens because the cache doesn't track deletions. Either remove the HTML file directly from your output directory, or use vāk rebuild to rebuild from scratch which will remove the deleted posts' HTML files.

Updated a template but changes aren't showing?

Template changes may not invalidate the cache properly. Run a full rebuild:

vāk rebuild
]]> Sat, 18 Jan 2025 12:00:00 +0530 RSS Feeds https://blog.vaak.com/rss-feeds https://blog.vaak.com/rss-feeds vāk automatically generates an RSS feed for your blog.

How it works

When you run vāk build, it creates feed.xml in your output directory. This file contains your published posts in RSS format, which readers can subscribe to using feed readers like Feedly, NetNewsWire, or Inoreader.

Subscription URL

Your feed is available at:

https://yourdomain.com/feed.xml

Link to it from your templates so readers can find it:

<a href="/feed.xml">Subscribe via RSS</a>

What's included

  • Published posts - All posts with status: published
  • Excluded - Posts with status: draft or status: unlisted

Posts appear in reverse chronological order (newest first).

Customizing the feed

Edit templates/feed.xml to customize your feed. The template receives the same allPosts data as the homepage.

Common customizations:

  • Change the feed title and description
  • Adjust how many posts appear in the feed
  • Modify the content format

Adding feed autodiscovery

Help feed readers find your RSS automatically by adding this to your HTML <head>:

<link rel="alternate" type="application/rss+xml"
      title="{{ siteName }}" href="{{ siteUrl }}/feed.xml">
]]> Fri, 17 Jan 2025 12:00:00 +0530 The 404 Page https://blog.vaak.com/404-page https://blog.vaak.com/404-page vāk generates a custom 404 error page for your blog.

What is it?

The 404.html page is shown when visitors try to access a URL that doesn't exist. Instead of a generic server error, they see your custom page.

Customizing it

Edit templates/404.html to match your blog's style:

<!DOCTYPE html>
<html>
<head>
  <title>Page Not Found - {{ siteName }}</title>
  <link rel="stylesheet" href="/style.css">
</head>
<body>
  <h1>404 - Page Not Found</h1>
  <p>The page you're looking for doesn't exist.</p>
  <p><a href="/">Go back home</a></p>
</body>
</html>

Available data

The 404 template receives:

  • siteUrl - Your site URL
  • siteName - Your site name

Deployment notes

How the 404 page works depends on your hosting provider:

GitHub Pages

Automatically serves 404.html for missing pages. No configuration needed.

Netlify

Automatically serves 404.html. You can also add a _redirects file for more control.

Vercel

Add a vercel.json to your output directory:

{
  "routes": [
    { "handle": "filesystem" },
    { "src": "/(.*)", "dest": "/404.html", "status": 404 }
  ]
}

Apache

Add to .htaccess:

ErrorDocument 404 /404.html

Nginx

Add to your server config:

error_page 404 /404.html;

Testing locally

With npx serve public, visiting a non-existent URL won't show your 404 page (serve doesn't support custom error pages). Deploy to test the actual behavior.

]]> Thu, 16 Jan 2025 12:00:00 +0530 The Archive Page https://blog.vaak.com/archive-page https://blog.vaak.com/archive-page vāk generates an archive page that lists all your posts grouped by year.

How it works

When you run vāk build, it creates archive.html in your output directory. This page shows all published posts organized chronologically.

Linking to the archive

Add a link to your archive from your homepage or navigation:

<a href="/archive.html">Archive</a>

Available data

The archive template receives:

  • postsByYear - Posts grouped by year
  • siteUrl - Your site URL
  • siteName - Your site name

postsByYear structure

[
  {
    year: 2025,
    posts: [
      { title: "...", date: "Jan 15, 2025", slug: "...", collections: [...] },
      { title: "...", date: "Jan 10, 2025", slug: "...", collections: [...] }
    ]
  },
  {
    year: 2024,
    posts: [...]
  }
]

Posts within each year are sorted newest first.

Customizing the template

Edit templates/archive.html to change the layout:

<h1>Archive</h1>

{% for group in postsByYear %}
  <section>
    <h2>{{ group.year }}</h2>
    <ul>
      {% for post in group.posts %}
        <li>
          <span>{{ post.date }}</span>
          <a href="./{{ post.slug }}">{{ post.title }}</a>
        </li>
      {% endfor %}
    </ul>
  </section>
{% endfor %}

Show post count per year

<h2>{{ group.year }} ({{ group.posts | length }} posts)</h2>

Include collections

{% for post in group.posts %}
  <li>
    <a href="./{{ post.slug }}">{{ post.title }}</a>
    {% if post.collections %}
      <span class="tags">
        {% for col in post.collections %}
          <a href="/collection-{{ col.slug }}.html">{{ col.name }}</a>
        {% endfor %}
      </span>
    {% endif %}
  </li>
{% endfor %}

Archive on the homepage

You can also use postsByYear on your homepage to show posts grouped by year instead of a flat list. The same data is available in index.html.

]]> Wed, 15 Jan 2025 12:00:00 +0530 Adding JavaScript https://blog.vaak.com/adding-javascript https://blog.vaak.com/adding-javascript vāk includes a js/ directory for JavaScript files.

Adding scripts

  1. Add your JavaScript file to the js/ folder
  2. Include it in your templates:
<script src="/js/my-script.js"></script>

Add this before the closing </body> tag in your templates.

Common use cases

Analytics

Add tracking scripts to monitor your blog's traffic:

<!-- In templates/post.html and templates/index.html -->
<script async src="https://analytics.example.com/script.js"></script>

Comments

Add a commenting system like Utterances (uses GitHub issues):

<!-- In templates/post.html -->
<script src="https://utteranc.es/client.js"
        repo="username/repo"
        issue-term="pathname"
        theme="github-light"
        crossorigin="anonymous"
        async>
</script>

Syntax highlighting

Enhance code blocks with Prism.js or highlight.js:

<link rel="stylesheet" href="/js/prism.css">
<script src="/js/prism.js"></script>

Dark mode toggle

<script src="/js/theme.js"></script>

Per-template scripts

You can add scripts to specific templates:

  • index.html - Homepage-only scripts
  • post.html - Post page scripts (comments, reading time)
  • archive.html - Archive-specific functionality

External scripts

For third-party scripts, link directly:

<script src="https://cdn.example.com/library.min.js"></script>
]]> Tue, 14 Jan 2025 12:00:00 +0530 Adding Images https://blog.vaak.com/adding-images https://blog.vaak.com/adding-images vāk includes an images/ directory for your image assets.

Using images in posts

  1. Add your image to the images/ folder
  2. Reference it in your markdown:
![Alt text](/images/my-photo.jpg)

Or with a relative path:

![Alt text](../images/my-photo.jpg)

Adding a favicon

The default templates look for a favicon at images/favicon.png. To add one:

  1. Create a square image (32x32 or 64x64 pixels works well)
  2. Save it as images/favicon.png

The favicon link in your templates:

<link rel="icon" href="/images/favicon.png">

Image optimization

vāk copies images as-is without processing. For best performance:

  • Compress images before adding them (use tools like ImageOptim, Squoosh, or TinyPNG)
  • Use appropriate formats - JPEG for photos, PNG for graphics with transparency, WebP for modern browsers
  • Size appropriately - Don't upload 4000px images if they'll display at 800px

Using images in templates

Reference images in your HTML templates:

<img src="/images/logo.png" alt="Site logo">

Or with the site URL for absolute paths:

<img src="{{ siteUrl }}/images/header.jpg" alt="Header">
]]> Mon, 13 Jan 2025 12:00:00 +0530 Collections https://blog.vaak.com/collections https://blog.vaak.com/collections Collections let you group related posts together. A post can belong to multiple collections.

How to use

Add a collections field to your post's frontmatter:

---
title: "My Post"
collections: Journal, Tutorials
---

That's it. Your post now belongs to the "Journal" and "Tutorials" collections.

Viewing collections

Each collection gets its own page at /collection-{slug}.html, where slug is a URL-safe version of the collection name.

Example: Feature collection

Using collections in templates

Collections are available in these templates: index.html, post.html, archive.html, and collection.html.

Each collection has two properties:

Property Description
name The collection name as written in frontmatter
slug URL-safe version of the name

Example usage in post.html:

{% for collection in collections %}
  <a href="/collection-{{collection.slug}}.html">{{collection.name}}</a>
{% endfor %}
]]> Sun, 12 Jan 2025 12:00:00 +0530 Styling Your Blog https://blog.vaak.com/styling-your-blog https://blog.vaak.com/styling-your-blog vāk uses a style.css file in your templates directory for styling.

How it works

The templates/style.css file is copied to your output directory during build. All your HTML templates can reference it:

<link rel="stylesheet" href="/style.css">

Basic customization

Edit templates/style.css to change your blog's appearance:

/* Typography */
body {
  font-family: Georgia, serif;
  line-height: 1.6;
  color: #333;
}

/* Links */
a {
  color: #0066cc;
}

/* Post titles */
h1 {
  font-size: 2rem;
  margin-bottom: 0.5rem;
}

/* Code blocks */
pre {
  background: #f5f5f5;
  padding: 1rem;
  overflow-x: auto;
}

Using Tailwind CSS

vāk has built-in Tailwind support. Just use Tailwind classes in your templates/style.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

/* Your custom styles */
.post-title {
  @apply text-3xl font-bold mb-4;
}

.post-date {
  @apply text-gray-600 mb-8;
}

.prose {
  @apply max-w-2xl mx-auto px-4 py-8;
}

vāk automatically processes Tailwind directives during build - no separate build step needed.

Adding custom fonts

Google Fonts

<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap" rel="stylesheet">

body {
  font-family: 'Inter', sans-serif;
}

Self-hosted fonts

Add font files to your images/ or js/ directory and reference them:

@font-face {
  font-family: 'MyFont';
  src: url('/images/myfont.woff2') format('woff2');
}

Dark mode

Add a dark mode with CSS:

@media (prefers-color-scheme: dark) {
  body {
    background: #1a1a1a;
    color: #e0e0e0;
  }
  a {
    color: #6db3f2;
  }
}

This automatically switches based on the user's system preference.

]]> Sat, 11 Jan 2025 12:00:00 +0530 Customizing Templates https://blog.vaak.com/customizing-templates https://blog.vaak.com/customizing-templates vāk uses Nunjucks for templating. You have full control over your blog's HTML.

Template files

When you run vāk init, these templates are created in templates/:

File Purpose
index.html Homepage
post.html Individual post pages
archive.html Archive page with posts grouped by year
collection.html Collection pages
404.html Error page
feed.xml RSS feed
style.css Stylesheet
post.md Template for new posts

Available data

Each template receives specific data when rendered.

index.html

  • allPosts - All published posts (newest first)
  • postsByYear - Posts grouped by year
  • collections - All collections
  • siteUrl, siteName

post.html

  • title, date, slug, content
  • collections - Collections this post belongs to
  • siteUrl, siteName

archive.html

  • postsByYear - Posts grouped by year
  • siteUrl, siteName

collection.html

  • collection - The collection (name and slug)
  • posts - Posts in this collection

404.html

  • siteUrl, siteName

Nunjucks basics

{# Display a variable #}
{{ title }}

{# Render HTML content (for markdown) #}
{{ content | safe }}

{# Loop through posts #}
{% for post in allPosts %}
  <a href="./{{ post.slug }}">{{ post.title }}</a>
{% endfor %}

{# Conditionals #}
{% if collections %}
  Tagged in {{ collections | length }} collections
{% endif %}

{# Limit to first 5 posts #}
{% for post in allPosts %}
  {% if loop.index <= 5 %}
    {{ post.title }}
  {% endif %}
{% endfor %}

Common customizations

Add navigation

<nav>
  <a href="/">Home</a>
  <a href="/archive.html">Archive</a>
  <a href="/feed.xml">RSS</a>
</nav>

Show collections on posts

{% if collections %}
  {% for col in collections %}
    <a href="/collection-{{ col.slug }}.html">{{ col.name }}</a>
  {% endfor %}
{% endif %}

Group posts by year on homepage

{% for group in postsByYear %}
  <h2>{{ group.year }}</h2>
  {% for post in group.posts %}
    <li><a href="./{{ post.slug }}">{{ post.title }}</a></li>
  {% endfor %}
{% endfor %}

For more, see the Nunjucks documentation.

]]> Fri, 10 Jan 2025 12:00:00 +0530 How to publish your blog https://blog.vaak.com/publish-blog https://blog.vaak.com/publish-blog Here's how to build and deploy your vāk blog.

Set environment variables

vāk needs two environment variables:

export SITE_URL=https://yourdomain.com
export SITE_NAME="Your Blog Name"

Add these to your shell config (~/.bashrc or ~/.zshrc) to make them permanent.

Optional variables

Variable Default Description
OUTPUT_DIR ./public Where generated files go
POSTS_DIR ./posts Where your markdown posts are

Build the blog

Run the build command:

./vaak.cjs build

This generates your static blog in the public/ directory (or your custom OUTPUT_DIR).

Preview locally

Before deploying, preview your blog locally:

npx serve public

Open http://localhost:3000 to see your blog.

Deploy

The public/ folder contains plain HTML, CSS, and JavaScript. Deploy it anywhere that serves static files:

GitHub Pages

Push the public/ folder to a gh-pages branch or configure GitHub Pages to serve from a directory.

Netlify / Vercel

Connect your repository and set the publish directory to public/.

Any static host

Upload the contents of public/ to your web server.

Rebuild when you make changes

After editing posts or templates, run ./vaak.cjs build again to regenerate your blog.

]]> Sun, 05 Jan 2025 12:00:00 +0530