Daniel Toranzo Pérez

Agent guide

This repository is a bilingual Jekyll CV and technical blog. This guide describes how to add articles, pages, and tools without breaking the existing design, SEO, or validation.

Ground rules

Do not commit directly to main. Create an issue, work on a branch, and open a pull request.
Branch names and commit messages are written in English and include the issue number.
Do not edit _site/. It is generated by Jekyll.
Keep the site bilingual (Spanish/English) and test both languages.
Keep the Apple-inspired visual language, responsive layout, and dark mode.
Do not reference the original CV template in user-facing content.
Prefer small, focused changes. Do not reformat unrelated files.

Repository facts

Generator: Jekyll 3.8 through the github-pages gem.
Markdown: Kramdown.
Syntax highlighting: Rouge.
Styles: css/main.scss is the source; css/main.css is committed and served.
JavaScript: vanilla JS in js/.
Sitemap: generated by jekyll-sitemap into _site/sitemap.xml.
Blog permalink: /blog/:year/:month/:day/:title/.
Live site: https://www.obocat.com.
Content validation: ruby script/check_bilingual_content.rb.

Article workflow

1. Create or choose an issue

Use an issue that describes the article or change. The issue title and body can be in English; the published article must be bilingual.

If gh is unavailable, use the GitHub API with credentials from git credential fill. Do not invent issue or pull-request numbers.

2. Create a branch from `main`

git switch main
git pull --ff-only
git switch -c feature/<issue-number>-<short-slug>

Example: feature/15-ios-tools-and-agent-guide.

3. Create the post

Use a lowercase ASCII slug:

_posts/YYYY-MM-DD-slug.markdown

The date in the filename is the publication date. Future-dated posts are excluded from normal builds; preview them with --future:

bundle exec jekyll build --future
bundle exec jekyll serve --future

Do not backdate a post just to make it visible in a normal build.

4. Front matter

Every post must include:

---
title: "Título en español"
title_en: "Title in English"
date: 2026-11-06 00:00:00
description: "Resumen en español para la tarjeta y SEO."
description_en: "English summary for the card and SEO."
lang: es
tags: [iOS, SwiftUI]
categories: blog
layout: blog
reading_time: 7
---

title_en and description_en are required by the validator.
Set reading_time manually on bilingual posts. The layout otherwise counts both languages together.
Keep tags consistent with the existing blog.
Use natural translations, not literal word-for-word translations.

5. Bilingual body

Wrap each language in a single container with markdown="1":

<div class="lang-es" lang="es" markdown="1">

Contenido en español.

</div>

<div class="lang-en" lang="en" markdown="1">

Content in English.

</div>

Rules:

Both blocks must exist and be non-empty.
Do not nest extra div.lang-es or div.lang-en wrappers.
Keep headings, code examples, links, and structure equivalent in both languages.
Previous/next navigation is generated automatically from post dates.

6. Writing and code examples

Explain the problem and the trade-offs, not only the API.
Prefer complete, runnable examples.
When an article illustrates a system API, use a system symbol or built-in value so the reader can paste the example without creating assets first. Mention how to swap in a custom asset when relevant.
Avoid undefined variables in snippets. If a snippet depends on a value, show the surrounding struct, property, or function.
Use #Preview when it makes the example easier to try in Xcode.
Type-check Swift examples when possible:
```
swiftc -typecheck /tmp/example.swift
```
For Apple documentation URLs containing parentheses or underscores, percent-encode the problematic characters so Kramdown does not break the link.
Verify technical claims against Apple documentation or a reproducible test. Add nuance instead of overstating a behavior.

7. Validate

Run the same checks as CI:

ruby script/check_bilingual_content.rb
bundle exec jekyll build --future

Check the generated page and sitemap:

test -f "_site/blog/YYYY/MM/DD/slug/index.html"
grep -n "/blog/YYYY/MM/DD/slug/" _site/sitemap.xml

If SCSS changed, compile the served stylesheet:

bundle exec sass --sourcemap=auto css/main.scss css/main.css

Then rebuild. Always commit the compiled css/main.css when SCSS changes.

8. Commit, push, and open a pull request

Use an English commit message with the issue number:

docs: add custom SF Symbols article (#13)

Push the branch and open a PR against main. The PR body should include:

Summary of the change.
Closes #<issue>.
Tests or checks run.
Any publication date or merge-order note.

After the PR check finishes, comment on the issue with:

Branch name.
Commit hash.
PR link.
Check result.
Publication date, if applicable.

9. Definition of done

Adding a page or tool

Add a page under its own directory, for example tools/index.html, with a layout and an explicit permalink.
Tool detail pages live under tools/<slug>/index.html and use layout: tool. Shared tool markup goes in _includes/tools/.
Put shared markup in _layouts/; put page-specific behavior in js/.
Use existing CSS variables (--bg, --text, --accent, --border, etc.) instead of hard-coded light/dark colors.
Add a header link if the page is a primary section.
Test mobile widths, keyboard focus, dark mode, and both languages.
Do not add a backend or external API to a tool unless the issue explicitly requires it. Browser-only tools must work as static files.
Verify the page is included in _site/sitemap.xml after building.
If a new page should not be indexed, set sitemap: false explicitly and explain why in the PR.

Local preview

bundle exec jekyll serve --future

Open http://127.0.0.1:4000/. Use the language switch to verify both versions. Future-dated posts require --future; without it they will not appear.

This site is open source. Improve this page.