Blog Writing Assistant Guide

This file contains instructions for AI assistants helping with blog post creation on this Jekyll-based blog.

Pre-Approved Tools and Permissions

The following tools are pre-approved for use when working on this blog:

Web Research

• WebFetch(domain:blog.mozilla.org) - Mozilla blog posts
• WebFetch(domain:hacks.mozilla.org) - Mozilla Hacks technical articles
• WebFetch(domain:firefox-source-docs.mozilla.org) - Firefox documentation
• WebFetch(domain:dig.watch) - Digital Watch Observatory
• WebSearch - General web search for research

Jekyll Operations

• Bash(bundle exec jekyll build) - Build the static site
• Bash(bundle exec jekyll serve) - Serve site locally at http://127.0.0.1:4000/

Blog Post Creation Workflow

1. Research Phase

• Use the Explore agent to understand blog structure and style
• Read existing blog posts in _posts/ to understand tone and format
• Use WebFetch and WebSearch to gather information about the topic
• Read relevant Mozilla documentation and blog posts

2. Post Structure

File naming: _posts/YYYY-MM-DD-post-title-slug.md

Frontmatter template:

---
layout: post
title: "Your Post Title"
date: YYYY-MM-DD
author: "Tarek Ziade"
tags: [Tag1, Tag2, Tag3, Tag4]
---

Content structure:

1. Opening paragraph (no heading) - sets context and hooks reader
2. Main sections with ## headings (never use #)
3. Personal insights and lessons learned
4. Optional: “Useful links” section at end

3. Writing Style Guidelines

Tone:

• First-person, conversational, reflective
• Technical but accessible
• Honest about learning journey and mistakes
• Professional but personal

Content:

• 50-120 lines typical (~2000-4000 words)
• Break into logical sections with clear headings
• Include concrete examples and technical details
• Share both successes and challenges
• End with actionable insights or forward-looking thoughts

Punctuation:

• Do NOT use em-dashes (—)
• Use periods to separate sentences
• Use colons (:) for introducing lists or explanations
• Use parentheses () for parenthetical information
• Use commas appropriately for flow

Topics:

• AI and machine learning in browsers
• Firefox development and features
• Privacy-first design
• Web platform technology
• Software engineering practices
• WebNN and browser APIs

Common patterns:

• Start with compelling hook or problem statement
• Section-based organization
• Balance technical depth with readability
• Include links to related resources
• Discuss open questions and future directions

4. Tags

Common tags used (choose 3-4 relevant ones):

• AI, Machine Learning, Firefox, Privacy, Browsers
• Web, WebNN, PDF.js, Accessibility, Local AI
• Add new tags as appropriate for the topic

5. Building and Testing

Build the site:

bundle exec jekyll build

Preview locally:

bundle exec jekyll serve

Then open http://127.0.0.1:4000/

Auto-regeneration: The serve command watches for file changes and rebuilds automatically.

6. Asset Management

Images:

• Store in /assets/img/
• Reference in posts: /assets/img/filename.jpg
• Use loading="lazy" attribute

CSS:

• Custom styles in /assets/css/custom.css
• Avoid inline styles

Key Technical Details

Site Configuration

• Jekyll version: 4.4.1
• Theme: Minima with customizations
• Pagination: 10 posts per page
• Plugins: jekyll-feed, jekyll-seo-tag, jekyll-sitemap, jekyll-paginate

URL Structure

• Posts: /:categories/:year/:month/:day/:title/
• Tags: /tags/#tag-name
• Feed: /feed.xml

Footer Note

All posts include automated footer: “Some of the content may be generated by AI.”

Mozilla-Specific Context

Key Projects to Reference

• Firefox ML Runtime: ONNX + Transformers.js based inference engine
• PDF.js Alt Text: First ML project, ViT + GPT-2, 180M parameters
• Smart Tabs: Local AI for tab management
• WebNN: Future of browser-based AI
• Privacy-first approach: All AI features run locally when possible

Important Links

• Firefox ML Docs: https://firefox-source-docs.mozilla.org/toolkit/components/ml/
• Mozilla Blog: https://blog.mozilla.org
• Mozilla Hacks: https://hacks.mozilla.org
• Model Hub: https://huggingface.co/Mozilla

Workflow Summary

1. Research: Explore repo, read existing posts, gather information
2. Draft: Create post in _posts/ with proper frontmatter
3. Build: Run bundle exec jekyll build
4. Preview: Run bundle exec jekyll serve and review at localhost:4000
5. Iterate: Make changes, auto-rebuild, review again
6. Finalize: Ensure all links work, tags are appropriate, style is consistent

Tips for Efficiency

• Use parallel tool calls when gathering information
• Read multiple blog posts simultaneously to understand style
• WebFetch Mozilla resources before drafting to get accurate technical details
• Keep post focused on 3-4 main points rather than trying to cover everything
• Balance technical depth with storytelling
• Always include “Useful links” section with relevant resources