# Docs Template

A starting point for Markdown-only documentation repos on the [Hellion Forge](https://gitea.hellion-forge.cloud/).

Use this for:

- specs and design documents
- architecture decision records (ADRs)
- runbooks and post-mortems
- internal wikis

This template is plain Markdown. If you want a rendered site, add MkDocs or Docusaurus on top — the structure here works as input for either.

---

## How to use this template

1. Click **"Use this template"** on the Forge.
2. Replace this README with one that describes your specific docs repo.
3. Drop content into the appropriate folders:
   - `specs/` — feature specs, requirements, design proposals
   - `decisions/` — ADRs (one file per decision, prefix `ADR-NNNN-`)
   - `runbooks/` — operational guides, post-mortems, troubleshooting

If a folder doesn't fit your use case, delete it.

---

## Conventions

- **One topic per file.** No mega-docs. Cross-link instead.
- **Filename = title slug.** Lowercase-kebab-case (`backup-strategy.md`, not `Backup Strategy.md`).
- **Index files** at folder roots (`specs/INDEX.md` etc.) link to all files in the folder.
- **Frontmatter** for status / dates if you use a generator that needs it. Plain Markdown otherwise.
- **No screenshots in the repo unless they're load-bearing** — link to external assets if possible.

---

## ADR template

Architecture Decision Records: one file per decision, append-only.

```markdown
# ADR-0001: Title

**Date:** 2026-05-09
**Status:** accepted | superseded by ADR-NNNN | deprecated

## Context

What's the problem we're solving? Constraints, history.

## Decision

What did we decide. Concrete and short.

## Consequences

What changes because of this. Both positive and negative.
```

See `decisions/ADR-0001-example.md` for a worked example.

---

## License

MIT — see `LICENSE`. (For docs that include third-party content, override accordingly.)