jxnl Blog Development

Development workflow for Jason Liu's personal blog and consulting website built with MkDocs Material. Includes AI-powered SEO automation, link management, and content generation tools.

Overview

This skill provides guidance for working with a technical blog that features AI/ML content, consulting services, RAG education courses, and personal writing. The site uses MkDocs Material for static site generation with custom automation scripts.

Repository Information

**Live site:** https://jxnl.co/

**Repository:** https://github.com/jxnl/blog/

**Content directory:** `docs/`

**Blog posts:** `docs/writing/posts/`

**Configuration:** `mkdocs.yml`

Build & Development Commands

```bash

Install dependencies (prefer uv)

uv pip install -r requirements-doc.txt

Start development server with live reload

mkdocs serve

Build static site

mkdocs build

or use the build script

./build_mkdocs.sh

Utility scripts

python check_links.py # Verify all markdown links

python generate_sitemap.py # Generate SEO sitemap with AI summaries

python generate_desc.py # Add AI-generated descriptions to posts

```

Architecture

**Static Site Generation:**

MkDocs with Material theme

Markdown files in `docs/` directory

Blog plugin for chronological posts

YouTube color scheme (dark theme)

Google Analytics (G-686PKP2V2V)

MathJax for mathematical notation

RSS feed enabled

**Content Structure:**

Blog posts: `docs/writing/posts/`

Custom CSS: `docs/stylesheets/`

Custom JavaScript: `docs/javascripts/`

Configuration: `mkdocs.yml`

**Automation Tools:**

AI-powered SEO metadata generation

Link verification and tracking

Shortlink management via Dub

Sitemap generation with summaries

Adding New Blog Posts

1. Create markdown file in `docs/writing/posts/`

2. Add frontmatter with required fields:

- date

- authors

- description

- categories

- draft status

3. Run `python generate_desc.py` to generate AI descriptions if needed

4. Verify links with `python check_links.py`

5. For external links, generate shortlinks with proper tagging

Shortlink Management

Always use the shortlinks CLI when adding external links to blog posts:

```bash

uv run python scripts/shortlinks.py "https://example.com" \

--title "Descriptive Title" \

--desc "Short description" \

--tags "tag1,tag2" \

--external-id "unique-id-for-link" \

--blog-tag "blog-slug-name"

```

The `--blog-tag` option is required and should match the blog post's slug or filename for analytics tracking.

Writing Style Guidelines

Thought Leadership Posts

**Structure:**

1. Core insights upfront

2. Glossary of key terms

3. Concrete examples

4. Actionable next steps

**Opening Format:**

Use "**The core insight:**" or "**Two core insights:**"

Include series positioning with links

Example: "_This is part of the [Series Name](./series-index.md). I'm focusing on X because it's where theory meets practice._"

**Subheadings:**

Use direct, descriptive headers

Avoid dramatic or corny language

Good: "Implementation Strategy"

Bad: "The Evolution from Chunks to Context"

**Citations:**

Weave research naturally to support arguments

Use descriptive link text ("research shows", "Anthropic's approach")

Position strategically to strengthen specific points

**Key Themes:**

Bad context is cheap but toxic

Computational cheapness ≠ business value

Coding agents as leading edge

Economics and ergonomics matter

Transferable principles across industries

**Tone:**

Concise with practical urgency

Concrete metrics and examples

First-person perspective from consulting experience

Honest about complexity

**Consulting Attribution:**

Early reference: "Through my [consulting work](https://jxnl.co/services/), I help companies..."

Conclude with collaboration invitation

Natural integration, not promotional

**Cross-linking:**

Use blog-crosslink-optimizer agent

Add natural internal links that provide reader value

Enhance navigation between related posts

Series Writing

**Context Engineering Series:**

Multi-post series on agentic RAG systems

Position each post within broader narrative

Include consistent glossary format

Link to services page

Mention consulting experience

End with series navigation footer

Use concrete metrics and business outcomes

Avoid overly dramatic subheadings

**Blog Post Titles:**

Use direct, actionable formats

Good: "Four Levels Every RAG System Should Implement"

Good: "Two Experiments We Need to Run on AI Agent Compaction"

Avoid abstract concepts

Content Guidelines

**Blog Post Frontmatter:**

```yaml

---

date: YYYY-MM-DD

authors:

- author-id

description: Brief description (can be AI-generated)

categories:

- Category Name

draft: false

---

```

**Internal Linking:**

Cross-reference related posts

Link to series index pages

Reference consulting services naturally

Use descriptive anchor text

**SEO Optimization:**

Run `generate_desc.py` for AI-generated descriptions

Generate sitemap with `generate_sitemap.py`

Verify all links with `check_links.py`

Tag external links with blog context

Technical Notes

Site uses Material Design for responsive UI

Custom color scheme based on YouTube branding

Blog plugin handles chronological organization

Static generation for performance and simple hosting

Python automation scripts for SEO and maintenance

Workflow Steps

1. **Before writing:** Review series positioning and related posts

2. **While writing:** Follow structure and tone guidelines, use shortlinks for external URLs

3. **After writing:** Run SEO scripts, verify links, optimize cross-references

4. **Before publishing:** Test with `mkdocs serve`, verify frontmatter, check draft status

5. **Publishing:** Build site with `mkdocs build` or `./build_mkdocs.sh`

Key Files

`mkdocs.yml` - Site configuration

`requirements-doc.txt` - Python dependencies

`docs/writing/posts/` - Blog post directory

`scripts/shortlinks.py` - Link management CLI

`check_links.py` - Link verification

`generate_sitemap.py` - SEO sitemap generation

`generate_desc.py` - AI description generator

jxnl blog development

Safety Concern