{"id":30066578,"url":"https://github.com/appthrust/karg","last_synced_at":"2025-08-08T07:44:31.668Z","repository":{"id":305184510,"uuid":"1021127857","full_name":"appthrust/karg","owner":"appthrust","description":"Transform Kubernetes CRD YAML files into beautiful, searchable API documentation. Generate comprehensive markdown docs from Custom Resource Definitions with zero configuration.","archived":false,"fork":false,"pushed_at":"2025-07-29T05:41:11.000Z","size":94,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-29T07:43:42.133Z","etag":null,"topics":["api-docs","cli","crd","custom-resources","devops","documentation","k8s","kubernetes","markdown"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/appthrust.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-16T23:49:21.000Z","updated_at":"2025-07-29T05:41:15.000Z","dependencies_parsed_at":"2025-07-18T20:15:04.540Z","dependency_job_id":"747807e9-088e-471d-bb0b-b7d61b72b0d4","html_url":"https://github.com/appthrust/karg","commit_stats":null,"previous_names":["appthrust/karg"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/appthrust/karg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Fkarg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Fkarg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Fkarg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Fkarg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/appthrust","download_url":"https://codeload.github.com/appthrust/karg/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Fkarg/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269385642,"owners_count":24408416,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-08T02:00:09.200Z","response_time":72,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-docs","cli","crd","custom-resources","devops","documentation","k8s","kubernetes","markdown"],"created_at":"2025-08-08T07:44:30.531Z","updated_at":"2025-08-08T07:44:31.596Z","avatar_url":"https://github.com/appthrust.png","language":"TypeScript","readme":"# KARG - Kubernetes API Reference Generator\n\nTransform your Kubernetes CRD YAML files into beautiful, searchable API documentation in seconds.\n\n```bash\n# Generate docs for all your CRDs\nkarg --input \"./crds/*.yaml\" --output-directory ./docs\n```\n\n## What is KARG?\n\n**KARG** (Kubernetes API Reference Generator) automatically generates comprehensive markdown documentation from your Custom Resource Definition (CRD) files. Perfect for:\n\n- 📚 **API Documentation** - Keep your CRD docs always up-to-date\n- 🤖 **AI/LLM Integration** - Generate docs optimized for AI assistants\n- 👥 **Team Collaboration** - Share clear API references with your team\n- 🔍 **API Discovery** - Understand CRD structures at a glance\n\n## Quick Start\n\n### Install\n\nUsing [Devbox](https://www.jetify.com/devbox):\n\n\u003c!-- begin:devbox_install - DON'T EDIT: This block will be replaced by CI --\u003e\n```bash\ndevbox add github:appthrust/karg/v0.4.0#karg\n```\n\u003c!-- end:devbox_install --\u003e\n\nUsing [Nix](https://nixos.org/):\n\n\u003c!-- begin:nix_install - DON'T EDIT: This block will be replaced by CI --\u003e\n```bash\nnix run github:appthrust/karg/v0.4.0#karg -- --help\n```\n\u003c!-- end:nix_install --\u003e\n\n#### Important: Version Pinning and Updates\n\nWe strongly recommend installing with a specific version tag (e.g., `/v0.6.0`) as shown above. This ensures:\n- ✅ Reproducible installations\n- ✅ Consistent behavior across environments\n- ✅ Explicit version control\n\n**Note**: `devbox update` does not work with GitHub Flake packages. This is due to the fundamental design of how Devbox integrates with Nix - GitHub Flakes are not registered in Nix profiles and thus cannot be updated via `nix profile upgrade`. This is a known limitation. \n\nIf you installed without a version tag:\n```bash\n# ❌ Not recommended - will pin to a specific commit\ndevbox add github:appthrust/karg#karg\n```\n\nTo update, you must manually reinstall:\n```bash\n# Remove the old version\ndevbox rm github:appthrust/karg#karg\n\n# Clean the cache\nrm -rf .devbox\n\n# Install the latest version with a tag\ndevbox add github:appthrust/karg/v0.7.0#karg\n\n# Restart your shell\nexit \u0026\u0026 devbox shell\n```\n\n### Generate Documentation\n\n```bash\n# Multiple files - one doc per CRD\nkarg --input \"./crds/*.yaml\" --output-directory ./docs\n\n# Single file - all CRDs combined\nkarg --input \"./crds/*.yaml\" --output-file ./api-reference.md\n\n# With detailed logging\nkarg --input \"./crds/*.yaml\" --output-directory ./docs --verbose\n```\n\n## Example Output\n\nKARG transforms this CRD:\n\n```yaml\napiVersion: apiextensions.k8s.io/v1\nkind: CustomResourceDefinition\nmetadata:\n  name: books.library.example.com\nspec:\n  group: library.example.com\n  versions:\n  - name: v1\n    schema:\n      openAPIV3Schema:\n        type: object\n        properties:\n          spec:\n            type: object\n            required: [\"title\", \"author\", \"isbn\"]\n            properties:\n              title:\n                type: string\n                description: Title of the book\n                minLength: 1\n                maxLength: 200\n```\n\nInto this beautiful documentation:\n\n\u003e ## Book\n\u003e \n\u003e Book represents a book in the library catalog\n\u003e \n\u003e - **API version:** `library.example.com/v1`\n\u003e - **Scope:** Namespaced\n\u003e - **Plural:** `books`\n\u003e - **Singular:** `book`\n\u003e \n\u003e ### Quick Reference\n\u003e \n\u003e | Field path    | Type     | Required | Description         |\n\u003e | ------------- | -------- | -------- | ------------------- |\n\u003e | `spec.title`  | `string` | ✓        | Title of the book   |\n\u003e | `spec.author` | `string` | ✓        | Author of the book  |\n\u003e | `spec.isbn`   | `string` | ✓        | ISBN-13 of the book |\n\u003e \n\u003e ### Spec\n\u003e \n\u003e #### `spec.title`\n\u003e \n\u003e Title of the book\n\u003e \n\u003e - **Type:** `string`\n\u003e - **Required**\n\u003e - **Constraints**\n\u003e   - **Min length:** `1`\n\u003e   - **Max length:** `200`\n\n## Features\n\n✨ **Smart Documentation**\n- Automatically extracts descriptions, types, and constraints\n- Supports nested objects and arrays\n- Handles validation rules and default values\n\n🎯 **Developer Friendly**\n- Clean markdown output\n- Consistent formatting\n- Perfect for GitHub/GitLab wikis\n\n🤖 **AI/LLM Optimized**\n- Structured format for easy parsing\n- Complete field information in context\n- Copy-paste ready examples\n\n## Real World Examples\n\nCheck out the `examples/` directory to see KARG in action:\n\n```bash\n# Try it yourself\nkarg --input examples/input.yaml --output-file my-api-docs.md\n\n# View pre-generated examples\nls examples/per-kind-output/\n```\n\nThe examples showcase various CRD patterns:\n- Simple resources with basic validation\n- Complex nested structures\n- Arrays and maps\n- Custom validation rules\n- Status subresources\n\n## CLI Options\n\n```\nkarg [options]\n\nOptions:\n  --input \u003cpattern\u003e              Glob pattern for CRD YAML files (required)\n  --output-directory \u003cdir\u003e       Generate one file per CRD\n  --output-file \u003cfile\u003e          Generate a single combined file\n  --verbose                     Enable detailed logging\n  --help                        Show help\n  --version                     Show version\n\nExamples:\n  karg --input \"./crds/*.yaml\" --output-directory ./docs\n  karg --input \"./manifests/**/*.yaml\" --output-file ./api.md\n  karg --input config.yaml --output-directory ./output --verbose\n```\n\n## Why KARG?\n\n🚀 **Fast** - Built with Bun for blazing fast performance\n\n🔒 **Safe** - AST-based generation prevents injection attacks\n\n📦 **Zero Config** - Works out of the box with standard CRDs\n\n🎨 **Beautiful Output** - Clean, consistent markdown every time\n\n## Installation Options\n\n### For Projects\n\nAdd to your project's documentation pipeline:\n\n```bash\n# Using Devbox (recommended to use version tags)\ndevbox add github:appthrust/karg/v0.6.0#karg\n\n# Using Nix (recommended to use version tags) \nnix profile install github:appthrust/karg/v0.6.0#karg\n```","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappthrust%2Fkarg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fappthrust%2Fkarg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappthrust%2Fkarg/lists"}