When a user wants to add an image to a blog post:
-
First check if the image already exists:
ls -R ~/rare_gits/blob/blog/
Ask the user: "I see these existing images - is your image already there or do we need to add a new one?"
-
If the image doesn't exist:
- Ask user: "Would you like me to help you add a new image? If so, please provide the image and I'll help place it in ~/rare_gits/blob/blog/"
- Images should use .webp format for best performance
- Use descriptive names that indicate the image content
-
Check if the post has an imagefeature in its front matter:
- If missing, add it using the first image:
imagefeature: https://github.com/idvorkin/blob/raw/master/blog/your-image-name.webp
- If already present, leave it unchanged as it's the post's primary image
- If missing, add it using the first image:
-
Once we confirm the image exists or after adding it, use one of these includes:
For right-floating images (preferred):
{% include blob_image_float_right.html src="blog/raccoon-your-image.webp" %}
For centered images:
{% include blob_image.html src="blog/raccoon-your-image.webp" %}
-
Place the include tag:
- For new posts: After the first paragraph
- For existing posts: Near relevant content
- Ensure there's a blank line before and after the include
-
After adding the image:
- If new image: Commit it to the blob repo
- Commit the blog post changes
-
File Names:
- Blog post files should have descriptive names without dates.
- Example:
advice.md
,how-to-learn.md
,productivity-tips.md
.
-
Drafts:
- Place new blog posts in the
_d
directory for drafts. - Example:
_d/advice.md
.
- Place new blog posts in the
-
Front Matter:
- Ensure the
permalink
field in the front matter is unique and descriptive. - Example:
permalink: /advice
- Ensure the
When working on a blog post:
-
Get the permalink from the post's front matter
-
Use this command to open the post in the default browser:
open http://localhost:4000{permalink}
-
If working on a specific section, append the anchor:
open http://localhost:4000{permalink}#{anchor}
Example:
- Full post:
open http://localhost:4000/laws-of-new-skills
- Specific section:
open http://localhost:4000/laws-of-new-skills#law-2-practice-makes-permanent
- Full post:
Note: Jekyll must be running locally (localhost:4000)
- For ANY commands that would use a pager or require user interaction, you should append
| /bin/cat
to the command (NOT justcat
as it's aliased tobat
). Otherwise, the command will break. You MUST do this for: git, less, head, tail, more, etc. - For commands that are long running/expected to run indefinitely until interruption, run them in the background.
Prefer returning from a function vs nesting ifs. Prefer descriptive variable names over comments.
When changing a post's permalink:
- Use the redirect_from front matter to maintain compatibility
- This ensures old links continue to work
- IMPORTANT: Do not use 'aliases' in front matter - it doesn't work. If you see 'aliases', convert it to redirect_from
- Example format:
--- permalink: /new-url redirect_from: - /old-url # ✅ correct way aliases: ["/old-url"] # ❌ wrong way - doesn't work ---
- Check existing links to the post in other content and update if needed
- The redirects are handled by Jekyll, no need to modify back-links.json
Note: See _posts/2018-01-01-fuck-pride.md for a good example of permalink redirection
- Get an overeview of the blog by making this read on
READ: back-links.json
- Get good example blog posts to immitate
READ: _posts/2020-04-01-Igor-Eulogy.md _d/pride.md back-links.json
- We are not going to write code, so ignore all coding conventions
- Before adding a blog post, always check if it exists, add it if it does.
- If the blog post is reference, add it as readonly
- This project also contains a jekyll blog, you'll often be expected to edit the blog content
_d
is drafts, by default put stuff in drafts folder so it's a simpler filename- Always include a markdown table of contents, and a nice permalink title
- Ask user what are good tags for the post
- Before creating a new entry, see if an entry already exists by running
qa_blog where "your exact question in quotes"
- Ask the user where they want to add the blog content. Do this by running:
qa_blog where "your exact question in quotes"
- Then inspect the output, and suggest what files to edit, and which should be readonly
- Fun and quirky
- Technical, but not boring
When modifying markdown headings:
- Always update the Table of Contents (TOC)
- The TOC is managed by vim-markdown-toc
- For new posts: Place TOC immediately after the first paragraph
- For existing posts: Don't move the TOC location
- Keep the special markers intact:
Note: Many posts use this format for the TOC section:
<!-- prettier-ignore-start -->
<!-- vim-markdown-toc-start -->
[TOC content]
<!-- vim-markdown-toc-end -->
<!-- prettier-ignore-end -->
When using lists that should be inserted into tables:
-
In the table, use the format
[lXX](lXX)
where:- The link text and href must both match exactly (e.g.,
[l31](l31)
) - XX is the list number (e.g., 31, 32, etc.)
- IMPORTANT: List numbers must be unique across the entire file
- If adding a new list, check existing lists in the file and use a new unique number
- The link text and href must both match exactly (e.g.,
-
Below the table, structure the lists like this:
<div/> - lXX - List item 1 - List item 2 <div/>
-
Important formatting rules:
- Each list must start with
<div/>
- First list item must be the list identifier (e.g.,
l31
) - List must end with
<div/>
- The list identifier in the table link must match exactly
- Never reuse list numbers within the same file
- Each list must start with
Example:
| Day | Activity |
| --- | ---------- |
| Sa | [l31](l31) |
<div/>
- l31
- Item 1
- Item 2
<div/>
Note: If you have multiple tables in the same file, ensure each uses different list numbers. For example:
- First table:
l31
,l32
- Second table:
l33
,l34
- Third table:
l35
,l36
When adding links in markdown documents:
- Always check
back-links.json
to find the correct redirect URL - Use the format
[visible text](/redirect-url)
- Example: For meditation content, use
[meditation](/siy)
since meditation redirects to the Search Inside Yourself page
When referencing books in blog posts:
-
First, analyze the blog content:
- Review the post's content and themes
- Check if there are any existing amazon.html includes
- If includes exist, ask user: "I see existing book references. Would you like to: a) Keep them where they are b) Move them to the standard location (after introduction) c) Replace them with new books d) Add additional books?"
- Identify any books explicitly mentioned
- Recommend relevant books based on the topics covered
- Ask user: "Based on the content about [topics], I recommend including these books:
- [Book 1] because [reason]
- [Book 2] because [reason] Would you like to include these or different books?"
-
After user confirms book selections:
- For each book, ask: "Would you like me to help find the ASIN for [book title]?"
- If yes, run:
tony search "What is the ASIN for [book title]? Search Amazon too"
- The ASIN will be in the Amazon URL after "/dp/"
- Example: amazon.com/dp/B0CP52YY8F -> ASIN is B0CP52YY8F
-
Use the amazon.html include with ASINs:
{% include amazon.html asin="ASIN1;ASIN2;ASIN3" %}
-
The include will:
- Create a centered table with book covers
- Each book gets a cell with:
- Cover image (120px max width)
- "View on Amazon" link with affiliate code (ighe-20)
- Images are styled with a light border and padding
- Books are arranged horizontally in a single row
-
Multiple books:
- Separate ASINs with semicolons
- Books will display side-by-side in the table
- Keep to 2-3 books per row for readability
- Each book gets equal spacing (10px padding)
-
Place the include:
- For new references: After introducing the books in the text
- For existing references: Ask user about preferred location
- Ensure there's a blank line before and after the include
-
Example:
This post draws from three excellent books on relationships. {% include amazon.html asin="B0CP52YY8F;B00OICLVBI;B07QGRGDKJ" %} Let's explore the key concepts...
The amazon.html include automatically handles:
- Responsive image sizing
- Consistent styling across all book references
- Proper affiliate link formatting
- Mobile-friendly layout
CHOP is the practice of using AI chat to assist with programming tasks. When making CHOP changes:
- Document all changes in this conventions file
- Follow consistent patterns for similar types of changes
- Use the chat history to maintain context and consistency
CHOW is the practice of using AI chat to assist with writing and content creation. Similar to CHOP but focused on prose and documentation rather than code.
When you want to include a summary of another page's content:
-
Use the
summarize-page
include with the format:{% include summarize-page.html src="/page-url" %}
-
Before adding the include:
- Always check
back-links.json
to confirm the correct permalink - The src should match the permalink, not the filename
- Example: Use
/siy
for meditation content, not/meditation
- Always check
-
The include will automatically:
- Pull in the description from the target page
- Add a link attribution to the source
- Format it with proper styling
-
Common usage patterns:
- After introducing a concept that's detailed elsewhere
- When listing related topics
- In sections that reference other content
-
Example:
**Affirmations** Reinforcing positive beliefs and mindsets I want to cultivate. {% include summarize-page.html src="/affirmations" %}
- No Emojis
- Do not use emojis in blog posts or documentation
- This includes titles, headers, and content
- Keep the writing style clean and professional
When you want to add an alert box to your content:
-
Use the
alert
include with the format:{% include alert.html content="Your alert message here" style="info" %}
-
Available styles:
primary
- Blue, used for primary actions/informationsecondary
- Gray, used for secondary informationsuccess
- Green, used for success messagesdanger
- Red, used for error messages or dangerous actionswarning
- Yellow, used for warning messagesinfo
- Light blue (default), used for informational messageslight
- Very light gray, used for subtle alertsdark
- Dark gray, used for high-contrast alerts
-
The style parameter is optional and defaults to "info"
-
Example usage:
{% include alert.html content="This is an info alert" %} {% include alert.html content="Warning! This action cannot be undone" style="warning" %} {% include alert.html content="Success! Your changes have been saved" style="success" %} {% include alert.html content="Error: Invalid input" style="danger" %}
-
Best practices:
- Use alerts sparingly to maintain their impact
- Choose appropriate styles for the message context
- Keep alert messages concise and clear
- Place alerts near the relevant content they reference