commit c6b4a88736ebe7a70d8d962fb5b72e89c7a48ec2 Author: user Date: Sat Feb 21 19:18:48 2026 +0100 feat: scaffold howtos project Collection of usage guides and cheatsheets. Includes project docs, topic template, and directory structure. diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..44fa520 --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +*.swp +*.swo +*~ +.DS_Store diff --git a/PROJECT.md b/PROJECT.md new file mode 100644 index 0000000..f6af7a0 --- /dev/null +++ b/PROJECT.md @@ -0,0 +1,31 @@ +# Project: howtos + +## Motivation + +Scattered notes, bookmarks, and `history | grep` are poor substitutes for well-organized reference material. This project centralizes practical knowledge into a consistent, maintainable format. + +## Goals + +- Provide quick-reference guides for daily tools and workflows +- Maintain a consistent structure across all topics +- Keep content concise and actionable — no tutorials, just references +- Make it easy to add new topics via a template + +## Architecture + +Flat file collection — no build step, no dependencies. Plain Markdown rendered by any viewer (terminal, browser, editor). + +``` +topics/.md # Individual howto files +docs/TEMPLATE.md # Template for new topics +``` + +## Dependencies + +None. Plain Markdown files. Optionally viewed with `glow`, `bat`, or any Markdown renderer. + +## Non-Goals + +- Not a tutorial site or blog +- Not a wiki with cross-linking +- Not auto-generated from `--help` output diff --git a/README.md b/README.md new file mode 100644 index 0000000..182d470 --- /dev/null +++ b/README.md @@ -0,0 +1,41 @@ +# howtos + +A curated collection of usage guides and cheatsheets for tools, languages, and workflows. + +## Purpose + +Quick-reference documentation — concise, searchable, copy-pasteable. Each topic lives in its own file under `topics/`. + +## Structure + +``` +topics/ + .md # One file per subject +docs/ + USAGE.md # How to use this collection + CHEATSHEET.md # Meta cheatsheet (formatting conventions) + INSTALL.md # Setup (minimal) +``` + +## Quick Start + +Browse `topics/` and open any `.md` file. Each howto follows a consistent format: + +- **Title** — what the tool/topic is +- **Common commands** — the 20% you use 80% of the time +- **Examples** — real-world usage +- **Gotchas** — things that bite + +## Adding a New Topic + +```bash +cp docs/TEMPLATE.md topics/.md +# Edit and fill in sections +``` + +## Conventions + +- One topic per file, lowercase hyphenated names (`docker-compose.md`, `git-rebase.md`) +- Code blocks with language hints for syntax highlighting +- Keep each file under 200 lines — split if larger +- Mark optional flags/args with `[]` diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..d942871 --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,24 @@ +# Roadmap + +## v0.1 — Foundation + +- [x] Project scaffold (README, docs, template) +- [ ] First batch of topics (5-10 core tools) +- [ ] Establish formatting conventions + +## v0.2 — Core Coverage + +- [ ] 20+ topics covering daily workflow +- [ ] Index/table of contents generation +- [ ] Tagging system (categories in frontmatter) + +## v1.0 — Complete Reference + +- [ ] 50+ topics +- [ ] Search script or integration +- [ ] Consistent quality across all files + +## Future + +- Topic freshness tracking (last-reviewed dates) +- Automated linting for format consistency diff --git a/TASKS.md b/TASKS.md new file mode 100644 index 0000000..a76d126 --- /dev/null +++ b/TASKS.md @@ -0,0 +1,12 @@ +# Tasks + +## Current + +- [x] Scaffold project structure +- [ ] Create topic template +- [ ] Write first topic + +## Backlog + +- [ ] Decide on category/tagging approach +- [ ] Add table of contents to README diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..45fc474 --- /dev/null +++ b/TODO.md @@ -0,0 +1,20 @@ +# TODO + +## Topics to Write + +- [ ] git — common workflows, rebase, stash, bisect +- [ ] ansible — playbook patterns, inventory, vault +- [ ] podman — build, run, compose, volumes +- [ ] jq — filters, select, map, slurp +- [ ] curl — headers, auth, methods, output +- [ ] systemd — units, journalctl, timers +- [ ] ssh — config, tunnels, keys, agent +- [ ] bash — parameter expansion, arrays, traps +- [ ] make — targets, variables, patterns +- [ ] vim — motions, registers, macros + +## Improvements + +- [ ] Format linter script +- [ ] Auto-generate index from topics/ +- [ ] Add last-reviewed date to template diff --git a/docs/CHEATSHEET.md b/docs/CHEATSHEET.md new file mode 100644 index 0000000..24c07c4 --- /dev/null +++ b/docs/CHEATSHEET.md @@ -0,0 +1,23 @@ +# Cheatsheet + +## Quick Reference + +| Action | Command | +|---------------------|--------------------------------------| +| List topics | `ls topics/` | +| Read topic | `bat topics/.md` | +| Add topic | `cp docs/TEMPLATE.md topics/.md` | +| Search across all | `grep -ri topics/` | + +## File Format + +Each topic file follows `docs/TEMPLATE.md`: + +``` +# +## Overview — one-liner description +## Common Commands — daily-driver commands +## Examples — real-world patterns +## Gotchas — pitfalls and edge cases +## See Also — related topics, links +``` diff --git a/docs/INSTALL.md b/docs/INSTALL.md new file mode 100644 index 0000000..b474835 --- /dev/null +++ b/docs/INSTALL.md @@ -0,0 +1,23 @@ +# Install + +## Prerequisites + +None. This is a plain Markdown collection. + +## Optional Tools + +For better terminal rendering: + +```bash +# bat — syntax-highlighted cat +sudo apt install bat + +# glow — terminal markdown renderer +sudo apt install glow +``` + +## Clone + +```bash +git clone ~/git/howtos +``` diff --git a/docs/TEMPLATE.md b/docs/TEMPLATE.md new file mode 100644 index 0000000..2bdbaaf --- /dev/null +++ b/docs/TEMPLATE.md @@ -0,0 +1,26 @@ +# Topic Name + +> One-line description of what this tool/subject is. + +## Common Commands + +```bash +# description +command --flag argument +``` + +## Examples + +```bash +# Practical example with context +command --option value +``` + +## Gotchas + +- Known pitfall or surprising behavior + +## See Also + +- `related-topic` — brief note +- [External reference](https://example.com) diff --git a/docs/USAGE.md b/docs/USAGE.md new file mode 100644 index 0000000..086abd7 --- /dev/null +++ b/docs/USAGE.md @@ -0,0 +1,29 @@ +# Usage + +## Browsing Topics + +Each topic is a standalone Markdown file in `topics/`: + +```bash +# List available topics +ls topics/ + +# Read a topic in terminal +cat topics/git.md # plain +bat topics/git.md # syntax highlighted +glow topics/git.md # rendered markdown +``` + +## Adding a New Topic + +```bash +cp docs/TEMPLATE.md topics/.md +``` + +Edit the file following the template structure. Keep it under 200 lines. + +## Naming Conventions + +- Lowercase, hyphenated: `docker-compose.md`, `git-rebase.md` +- One topic per file +- Use the tool/subject name as the filename