# ShortNews Markdown corpus (for AI agents & LLMs)

This folder is a **clean Markdown export** of every ShortNews article on shortstereo.com.

## Purpose

- Give AI agents / LLM tools structured, low-noise article text
- Preserve metadata (title, date, category, canonical URL, image)
- Mirror the live hierarchy: **Year → Category → Topic**

## Layout

```text
blog/markdown/
  README.md          # this file
  INDEX.md           # table of contents
  catalog.json       # machine-readable catalog
  {year}/
    {category}/      # technology | design | branding | global
      {slug}.md
```

## Front matter fields

Each `.md` file starts with YAML front matter:

| Field | Meaning |
|-------|---------|
| `title` | Article title |
| `description` | Short summary |
| `date` | Publish date (`YYYY-MM-DD`) |
| `year` | Year folder |
| `category` | Technology / Design / Branding / Global |
| `category_slug` | URL slug for category |
| `url` / `canonical` | Live HTML URL (source of truth for users) |
| `image` / `image_url` | Hero image path / absolute URL |
| `source_html` | Path to the HTML file in this repo |
| `publisher` | Always Short Stereo |

## How to use (agents)

1. Start at site root **`/llms.txt`** for discovery.
2. Prefer **`catalog.json`** to list or filter posts.
3. Load individual `.md` files for full text.
4. Cite the **`url`** field when attributing content.
5. Treat HTML at `url` as the public canonical page; Markdown is a derivative for machines.
6. Full list of Markdown URLs: **`/sitemap-markdown.xml`**.

## Regenerating

```bash
cd HTML_Website
python tools/export_blog_markdown.py
```

`generate_blog.py` also writes a Markdown file when you create a new post.

## License / attribution

Editorial content by **Short Stereo** (ShortNews). Generated 2026-07-28.