# Blog handbook

This handbook explains how to write for this blog, develop its application, and keep it maintainable. The Markdown files in `docs/` are also the source of the documentation published at `/docs`.

## For blog authors

Start with [your first post](https://pufanyi.com/docs/writing/first-post), then use the references for [Markdown and math](https://pufanyi.com/docs/writing/markdown), [images, diagrams, and embeds](https://pufanyi.com/docs/writing/media), and [citations](https://pufanyi.com/docs/writing/references). The [publishing checklist](https://pufanyi.com/docs/writing/publishing) covers previewing, updates, and moving an existing article.

Authors importing old material should also read [content migrations](https://pufanyi.com/docs/content-migrations). The ML Revisited series has additional [editorial principles](https://pufanyi.com/docs/ml-editorial).

## For developers

Follow [local development](https://pufanyi.com/docs/development) to install the pinned toolchain and start the watcher. Read [architecture](https://pufanyi.com/docs/architecture) before changing generation or browser lifecycles. Use [configuration](https://pufanyi.com/docs/configuration), [testing](https://pufanyi.com/docs/testing), and [deployment](https://pufanyi.com/docs/deployment) for the corresponding workflows.

[Maintaining documentation](https://pufanyi.com/docs/documentation) explains which pages to update with a code change, how the documentation site works, and how to add a page. [Dependency policy](https://pufanyi.com/docs/dependencies) records upgrade constraints; [browser troubleshooting](https://pufanyi.com/docs/browser-troubleshooting) covers host-specific setup problems.

## Where things live

| Source                                       | Purpose                                                    | Edited by                     |
| -------------------------------------------- | ---------------------------------------------------------- | ----------------------------- |
| `content/posts/<slug>/index.mdx`             | Article prose and front matter                             | Authors                       |
| Article assets, `styles.css`, and `scripts/` | Images, diagrams, and interactive examples                 | Authors and developers        |
| `content/cv.yaml`                            | Profile and CV content                                     | Authors                       |
| `configs/`                                   | Site, archive, comments, and redirect settings             | Maintainers                   |
| `docs/`                                      | This handbook and maintenance records                      | Everyone changing the project |
| `src/app/` excluding `data/`                 | Angular routes, components, and browser behavior           | Developers                    |
| `scripts/`                                   | Content generation, validation, and deployment preparation | Developers                    |
| `src/app/data/`, `.generated/`, and `dist/`  | Generated modules, exports, and production output          | Build tools only              |

## Reading maintenance records

The [ordered maintenance tasks](https://pufanyi.com/docs/maintenance/tasks) explain the completed six-dimension review and its validation. The [original audit](https://pufanyi.com/docs/audits/2026-09-12-maintainability) is a historical snapshot: its findings describe the code before those fixes. Use the current developer guides for present behavior and the records to understand decisions, measurements, and known tradeoffs.

## Documentation and changes

Update the relevant guide in the same change as code, configuration, or authoring behavior. Local development regenerates documentation when saved; production publishes it with the next site deployment. There is no separate copy of the prose and no separate documentation deployment.