{"id":44599037,"url":"https://github.com/marad/frontmatter","last_synced_at":"2026-02-14T09:10:53.860Z","repository":{"id":297650255,"uuid":"997469437","full_name":"marad/frontmatter","owner":"marad","description":"A powerful CLI tool for managing YAML frontmatter in text files","archived":false,"fork":false,"pushed_at":"2025-11-14T15:06:02.000Z","size":6532,"stargazers_count":6,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-14T17:18:15.440Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/marad.png","metadata":{"files":{"readme":"README.adoc","changelog":"CHANGELOG.adoc","contributing":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-06-06T15:22:34.000Z","updated_at":"2025-11-14T15:05:55.000Z","dependencies_parsed_at":null,"dependency_job_id":"3c6fcab9-c502-4076-ae6c-84adcfd99aab","html_url":"https://github.com/marad/frontmatter","commit_stats":null,"previous_names":["marad/frontmatter"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/marad/frontmatter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marad%2Ffrontmatter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marad%2Ffrontmatter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marad%2Ffrontmatter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marad%2Ffrontmatter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marad","download_url":"https://codeload.github.com/marad/frontmatter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marad%2Ffrontmatter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29441317,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T07:24:13.446Z","status":"ssl_error","status_checked_at":"2026-02-14T07:23:58.969Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-02-14T09:10:53.264Z","updated_at":"2026-02-14T09:10:53.854Z","avatar_url":"https://github.com/marad.png","language":"Go","funding_links":[],"categories":["\u003ca name=\"data-management-json\"\u003e\u003c/a\u003eData management - JSON/YAML/etc."],"sub_categories":[],"readme":"// :toc: up\n// :toclevels: 1\n// :sectnums:\n:source-highlighter: highlight.js\n:icons: font\n:experimental:\n:description: A powerful CLI tool for managing YAML frontmatter in text files\n\n= Frontmatter CLI Tool\n\nimage:https://github.com/marad/frontmatter/workflows/CI/badge.svg[CI Status]\nimage:https://img.shields.io/badge/Go-1.21+-blue.svg[Go Version]\nimage:https://img.shields.io/badge/License-MIT-green.svg[License]\nimage:https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey[Platform]\n// image:https://codecov.io/gh/marad/frontmatter/branch/main/graph/badge.svg[Coverage Status]\n\nA fast, efficient CLI tool for managing YAML frontmatter in text files. Built with Go and optimized for performance with large files.\n\n== Features\n\n* ✅ **Add frontmatter** to files that don't have it\n* ✅ **Modify specific fields** without affecting others\n* ✅ **Retrieve frontmatter content** or specific fields\n* ✅ **Delete frontmatter** entirely or specific fields\n* ✅ **Nested field support** with dot notation (`object.field`)\n* ✅ **Multiple operations** in a single command\n* ✅ **Dry-run mode** to preview changes\n* ✅ **Performance optimized** for large files\n* ✅ **Safe atomic writes** to prevent data corruption\n* ✅ **Exit codes** for scripting and automation\n\n== Installation\n\n=== From Source\n\n[source,bash]\n----\ngit clone https://github.com/marad/frontmatter.git\ncd frontmatter\ngo build -o frontmatter main.go\n----\n\n=== Using Go Install\n\n[source,bash]\n----\ngo install github.com/marad/frontmatter@latest\n----\n\n== Usage\n\n[source,bash]\n----\nfrontmatter [get|set|delete] [--dry-run] [...] \u003cfile\u003e\n----\n\n=== Commands\n\n==== Setting Fields\n\nSet a single field:\n[source,bash]\n----\nfrontmatter set message=\"Hello World\" file.md\n----\n\nSet nested fields with dot notation:\n[source,bash]\n----\nfrontmatter set object.field=5 file.md\n----\n\nSet multiple fields at once:\n[source,bash]\n----\nfrontmatter set a=1 b=value c=\"text with spaces\" file.md\n----\n\n==== Getting Fields\n\nGet a specific field:\n[source,bash]\n----\nfrontmatter get message file.md\n----\n\nGet the entire frontmatter:\n[source,bash]\n----\nfrontmatter get file.md\n----\n\n==== Deleting Fields\n\nDelete the entire frontmatter:\n[source,bash]\n----\nfrontmatter delete file.md\n----\n\nDelete specific fields:\n[source,bash]\n----\nfrontmatter delete title file.md\nfrontmatter delete first second file.md\n----\n\nDelete nested fields:\n[source,bash]\n----\nfrontmatter delete object.field file.md\n----\n\n=== Flags\n\n==== `--dry-run`\n\nPreview changes without modifying the file:\n[source,bash]\n----\nfrontmatter set title=\"New Title\" --dry-run file.md\n----\n\n== Data Types\n\nThe tool automatically detects and handles various data types:\n\n* **Strings**: `message=\"Hello World\"`\n* **Integers**: `count=42`\n* **Floats**: `price=19.99`\n* **Booleans**: `published=true`\n* **Arrays**: `tags=[tag1,tag2,tag3]`\n* **Objects**: `config={\"key\":\"value\"}`\n\n== Examples\n\n=== Basic Usage\n\nCreate a new file with frontmatter:\n[source,bash]\n----\necho \"# My Article\" \u003e article.md\nfrontmatter set title=\"My First Post\" author=\"John Doe\" article.md\n----\n\nResult:\n[source,yaml]\n----\n---\ntitle: My First Post\nauthor: John Doe\n---\n# My Article\n----\n\n=== Working with Nested Data\n\n[source,bash]\n----\nfrontmatter set config.database.host=\"localhost\" config.database.port=5432 article.md\n----\n\nResult:\n[source,yaml]\n----\n---\nconfig:\n  database:\n    host: localhost\n    port: 5432\n---\n----\n\n=== Querying Data\n\n[source,bash]\n----\n# Get specific field\nfrontmatter get title article.md\n# Output: My First Post\n\n# Get nested field\nfrontmatter get config.database.host article.md\n# Output: localhost\n\n# Get entire frontmatter as YAML\nfrontmatter get article.md\n----\n\n=== Batch Operations\n\n[source,bash]\n----\n# Set multiple fields\nfrontmatter set \\\n  title=\"Updated Title\" \\\n  updated=\"2025-06-06\" \\\n  tags=\"[tech,golang,cli]\" \\\n  article.md\n\n# Delete multiple fields\nfrontmatter delete draft updated article.md\n----\n\n== Exit Codes\n\nThe tool uses standard exit codes for scripting:\n\n* `0` - Success\n* `1` - General error (invalid arguments, file errors, etc.)\n* `2` - Not found (field doesn't exist, no frontmatter found)\n\n=== Scripting Example\n\n[source,bash]\n----\n#!/bin/bash\nif frontmatter get published article.md; then\n    echo \"Article is published\"\nelse\n    echo \"Article is not published or field doesn't exist\"\nfi\n----\n\n== Performance\n\nThe tool is optimized for performance with large files:\n\n* **Optimized I/O**: Only reads frontmatter section for `get` operations\n* **Atomic writes**: Uses temporary files to prevent corruption\n* **Memory efficient**: Streams large files instead of loading entirely into memory\n\n== File Format Support\n\nThe tool works with any text file containing YAML frontmatter:\n\n* **Markdown files** (`.md`, `.markdown`)\n* **HTML files** (`.html`, `.htm`)\n* **Text files** (`.txt`)\n* **Any other text format**\n\n[source,yaml]\n----\n---\ntitle: My Document\nauthor: John Doe\ndate: 2025-06-06\ntags: [example, demo]\nconfig:\n  theme: dark\n  language: en\n---\n\nYour document content goes here...\n----\n\n== Development\n\n=== Requirements\n\n* Go 1.21+ (tested on 1.21.x through 1.24.x)\n* Dependencies: `github.com/goccy/go-yaml`\n\n=== CI/CD\n\nThe project uses GitHub Actions for continuous integration and delivery:\n\n* **Automated testing** on multiple Go versions (1.21.x - 1.24.x)\n* **Cross-platform builds** (Linux, macOS, Windows, FreeBSD)\n* **Security scanning** with gosec\n* **Automated releases** with pre-built binaries\n\n=== Building\n\n[source,bash]\n----\ngo build -o frontmatter main.go\n----\n\n=== Testing\n\n[source,bash]\n----\ngo test -v\n----\n\nThe test suite includes 30+ comprehensive end-to-end tests that are run on the binary to ensure correct functionality.\n\n== Contributing\n\nI'll be happy to accept contributions! You can suggest changes, report issues, or submit pull requests. Let's talk!\n\nMy idea for this tool is to be pretty minimal but do its thing well.\n\n=== Guidelines\n\n* Follow Go best practices and conventions\n* Add tests for new functionality\n* Update documentation as needed\n* Ensure all tests pass before submitting\n\n== License\n\nThis project is licensed under the MIT License - see the link:LICENSE[LICENSE] file for details.\n\n== Changelog\n\nSee link:CHANGELOG.adoc[CHANGELOG.adoc] for detailed version history and release notes.\n\n== Acknowledgments\n\n* Built with https://github.com/goccy/go-yaml[goccy/go-yaml] for YAML processing\n\n== Support\n\nIf you encounter any issues or have questions:\n\n* Check the examples above\n* Review the test cases in `main_test.go`\n* Open an issue on GitHub\n* Verify your YAML syntax is valid\n\n---\n\n*Happy frontmatter managing! 🚀*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarad%2Ffrontmatter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarad%2Ffrontmatter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarad%2Ffrontmatter/lists"}