generated from eblume/project-template
57 lines
2.4 KiB
Markdown
57 lines
2.4 KiB
Markdown
|
# project-template
|
||
|
|
|
||
|
|
A personal project template with opinionated infrastructure for documentation, CI, and AI-assisted development.
|
||
|
|
|
||
|
|
## What's Included
|
||
|
|
|
||
|
|
- **Documentation** — [Diataxis](https://diataxis.fr/)-structured docs built with [Quartz](https://quartz.jzhao.xyz/)
|
||
|
|
- **Changelog** — [Towncrier](https://towncrier.readthedocs.io/) fragment-based changelog
|
||
|
|
- **CI/CD** — [Dagger](https://dagger.io/) pipelines + Forgejo `build` and `release` workflows
|
||
|
|
- **Pre-commit hooks** — [prek](https://github.com/dustinblackman/prek) with linting, formatting, secret detection
|
||
|
|
- **AI assistance** — `AGENTS.md` + structured docs for Claude Code (C0/C1/C2 change process, Mikado method)
|
||
|
|
- **Task runner** — [mise](https://mise.jdx.dev/) tasks for docs validation, Mikado chain management, release preview, and runner inspection
|
||
|
|
|
||
|
|
## Forking This Template
|
||
|
|
|
||
|
|
This is a **Forgejo template repository**. When you create a new repo from this template, Forgejo automatically expands variables like `${REPO_NAME}` and `${REPO_OWNER}` in key files — handling most customization automatically.
|
||
|
|
|
||
|
|
After creating your repo, the remaining manual steps are:
|
||
|
|
|
||
|
|
1. Set `baseUrl` in `docs/quartz.config.ts` to your docs site domain
|
||
|
|
2. Rename `.dagger/src/project_template_ci/` directory and update class names to match your project
|
||
|
|
3. Review and tailor the project structure section in `AGENTS.md`
|
||
|
|
4. Add license information to `README.md`
|
||
|
|
5. Remove the "First-Time Setup" section from `AGENTS.md` and this section from `README.md`
|
||
|
|
|
||
|
|
If you use Claude Code, it will prompt you to resolve remaining TODOs at the start of your first session.
|
||
|
|
|
||
|
|
## Getting Started
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# Install git hooks
|
||
|
|
prek install && prek install --hook-type commit-msg
|
||
|
|
|
||
|
|
# Run all pre-commit checks
|
||
|
|
prek run --all-files
|
||
|
|
|
||
|
|
# List available tasks
|
||
|
|
mise tasks
|
||
|
|
|
||
|
|
# Build docs (requires Dagger)
|
||
|
|
dagger call build-docs --src=. --version=dev export --path=./docs-dev.tar.gz
|
||
|
|
```
|
||
|
|
|
||
|
|
## Project Structure
|
||
|
|
|
||
|
|
```
|
||
|
|
./docs/ # documentation (Diataxis, Quartz)
|
||
|
|
./docs/changelog.d/ # leave only .gitkeep in the template; generated repos add towncrier fragments here
|
||
|
|
./.dagger/ # Dagger module backing docs builds and releases
|
||
|
|
./.forgejo/workflows/ # generic build/release workflows for generated repos
|
||
|
|
./.forgejo/scripts/ # optional per-project hooks consumed by those workflows
|
||
|
|
./mise-tasks/ # scripts via `mise run`
|
||
|
|
```
|
||
|
|
|
||
|
|
## License
|
||
|
|
|
||
|
|
<!-- TODO: Add license information -->
|