rsarai.xyz

Create a new Markdown file inside _posts/
Name it using the format: YYYY-MM-DD-your-post-title.md (the date is required)
Add the front matter at the top of the file
Write your content in Markdown below the front matter

Post front matter template

---
layout: post
title: Your Post Title Here
categories: [category1, category2]
excerpt: A short description shown in the blog listing page
last_modified_at:
---

Your content goes here. Write in Markdown.

Field	Required	Description
`layout`	Yes	Always use `post`
`title`	Yes	The title displayed on the page and blog listing
`categories`	No	Array of categories, e.g. `[software, open source]`
`excerpt`	No	Short summary shown on the blog listing page
`last_modified_at`	No	Date of last update; if set, shows "(Updated: ...)" on the post

Example

---
layout: post
title: The architecture of open source applications [Audacity]
categories: [software, open source]
excerpt: This post summarizes Chapter 2 of the book The architecture of open source applications - Vol I
last_modified_at:
---

Your post body in Markdown...

Working with Drafts

Drafts are posts you're still working on. They live in the _drafts/ folder and do not require a date in the filename.

_drafts/
  my-upcoming-post.md

Drafts are not included in the normal build. To preview them locally:

bundle exec jekyll serve --drafts

When the draft is ready, move the file to _posts/ and add the date prefix to the filename:

mv _drafts/my-upcoming-post.md _posts/2026-02-14-my-upcoming-post.md

Adding Images

Create a folder inside images/ matching your post (convention used in this blog):
```
images/2026-02-14-my-post-title/
```
Place your image files there

Reference them in your post with:

<img
  src="/images/2026-02-14-my-post-title/my-image.png"
  alt="Description of the image"
  title="Tooltip text"
/>

Or using Markdown syntax:

![Description](/images/2026-02-14-my-post-title/my-image.png)

Creating a New Page

Pages (non-blog content like About, Ideas, Links) live in _pages/. To create one:

Add a Markdown file in _pages/, e.g. _pages/my-page.md
Use the page layout:

---
layout: page
title: My Page
permalink: /my-page/
---

Page content here...

Optionally add a link to it in the sidebar navigation by editing _layouts/default.html

Project Structure

.
├── .github/workflows/
│   └── jekyll.yml       # GitHub Actions deployment workflow
├── _config.yml          # Site configuration (name, URL, plugins, etc.)
├── _drafts/             # Unpublished draft posts (no date in filename)
├── _includes/           # Reusable HTML partials (analytics, disqus, icons)
├── _layouts/            # Page templates (default, post, page)
├── _pages/              # Standalone pages (about, books, ideas, links, etc.)
├── _posts/              # Published blog posts (YYYY-MM-DD-title.md)
├── _sass/               # SCSS partials (variables, highlights, layout)
├── assets/
│   └── style.scss       # Main stylesheet (imports _sass partials)
├── blog/
│   └── index.html       # Blog listing page with pagination
├── fonts/               # Custom fonts
├── images/              # Post images, organized by post name
├── index.html           # Homepage
├── search.json          # JSON feed for search functionality
├── 404.md               # Custom 404 page
├── CNAME                # Custom domain: www.rsarai.xyz
├── Gemfile              # Ruby dependencies
├── Gemfile.lock         # Locked dependency versions
└── README.md            # This file

Configuration

All site settings are in _config.yml. Key settings:

Setting	Value / Description
`name`	`Rebeca Sarai`
`url`	`https://rsarai.xyz`
`permalink`	`/:title/` (clean URLs based on post title)
`paginate`	`50` (posts per page on the blog listing)
`paginate_path`	`/blog/page:num/`
`kramdown`	GitHub Flavored Markdown with Rouge syntax highlighting
`google_analytics`	`UA-158115790-1`

Important: Changes to _config.yml require restarting the Jekyll server (Ctrl+C and re-run bundle exec jekyll serve).

Styling

Main stylesheet: assets/style.scss (imports all partials)
Variables (colors, fonts, breakpoints): _sass/_variables.scss
Syntax highlighting: _sass/_darcula.scss
Homepage styles: _sass/_home.scss
Icon styles: _sass/_svg-icons.scss

Deploying

This blog is deployed via GitHub Actions to GitHub Pages. The workflow file lives at .github/workflows/jekyll.yml.

How it works:

Write or edit content locally
Preview it with bundle exec jekyll serve

Commit and push to the master branch:

git add .
git commit -m "Add new post: your post title"
git push origin master

GitHub Actions automatically builds (with Jekyll 4) and deploys the site to https://rsarai.xyz

The custom domain www.rsarai.xyz is configured via the CNAME file in the repo root.

One-time setup (already done if you're reading this):

In your GitHub repository, go to Settings > Pages > Source and select GitHub Actions (instead of "Deploy from a branch").

Quick Reference

Task	Command
Install dependencies	`bundle install`
Run locally	`bundle exec jekyll serve`
Run with drafts	`bundle exec jekyll serve --drafts`
Run with live reload	`bundle exec jekyll serve --livereload`
Build only (no server)	`bundle exec jekyll build`
Create a new post	Add `_posts/YYYY-MM-DD-title.md` with front matter
Create a draft	Add `_drafts/title.md` with front matter
Publish a draft	Move from `_drafts/` to `_posts/` with date prefix
Deploy	`git push origin master`

Credits

Theme based on Reverie by Amit Merchant.