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
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.
For CLIs, use a Typer app.
Use ic
for logging.
Use Rich for pretty printing.
Use Loguru for logging.
Use Typer for CLI apps.
Use Pydantic for data validation.
Use types; when using types, prefer using built-ins like foo | None
vs foo: Optional[str]
.
When using Typer, use the latest syntax for arguments and options.
name: Annotated[Optional[str], typer.Argument()] = None
def main(name: Annotated[str, typer.Argument()] = "Wade Wilson"):
lastname: Annotated[str, typer.Option(help="Last name of person to greet.")] = "",
formal: Annotated[bool, typer.Option(help="Say hi formally.")] = False,
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:
<!-- vim-markdown-toc-start --> [TOC content here] <!-- vim-markdown-toc-end -->
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
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