{"id":22980972,"url":"https://github.com/rubyworks/indexer","last_synced_at":"2025-08-13T17:33:41.566Z","repository":{"id":4145704,"uuid":"5259391","full_name":"rubyworks/indexer","owner":"rubyworks","description":"Canonical Metadata Specification for Software Projects","archived":false,"fork":false,"pushed_at":"2013-08-07T22:44:41.000Z","size":928,"stargazers_count":1,"open_issues_count":4,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-01T08:54:44.646Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rubyworks.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-08-01T13:15:26.000Z","updated_at":"2020-10-18T19:25:37.000Z","dependencies_parsed_at":"2022-08-20T23:10:10.407Z","dependency_job_id":null,"html_url":"https://github.com/rubyworks/indexer","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyworks%2Findexer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyworks%2Findexer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyworks%2Findexer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rubyworks%2Findexer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rubyworks","download_url":"https://codeload.github.com/rubyworks/indexer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229773540,"owners_count":18122031,"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","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":"2024-12-15T01:46:20.660Z","updated_at":"2024-12-15T01:46:21.166Z","avatar_url":"https://github.com/rubyworks.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# INDEXER\n\n**Enable Your Project's Metadata**\n\n[![Build Status](https://secure.travis-ci.org/rubyworks/indexer.png)](http://travis-ci.org/rubyworks/indexer)\n[![Gem Version](https://badge.fury.io/rb/indexer.png)](http://badge.fury.io/rb/indexer)\n\n\n## [What is Indexer?](#whatis)\n\nIndexer provides projects with a universal metadata format.\n\nIndexer defines a *canonical* project metadata specification which is both\ndetailed and strict. The strictness of the specification makes the format simple\nenough for developers to use without an intermediate API. Although Indexer also\nprovides a convenience API for working with the specification and its data more\nloosely when suitable to the usecase. Indexer also specifies a standard\nlocation for canonized metadata to be kept, in a `.index` file.\n\nIndexer provides a tool to import metadata from external sources. Indexer can\nhandle a variety of metadata source formats, including YAML, HTML Microformats\nand Ruby DSL scripts.\n\n\n## [Features](#features)\n\n* YAML-based format for universal accessibility.\n* Platform and programming language agnostic.\n* Canonical specification provides idempotent access.\n* Convenient Ruby API available.\n* Supports custom metadata fields.\n\n\n## [Instruction](#instruction)\n\n### [Installation](#installation)\n\nIndexer is a Ruby application, so as long as you have Ruby installed, it is easy\nto install Indexer via RubyGems.\n\n    $ gem install indexer\n\n### [Metadata Sources](#sources)\n\nIndexer is capable of generating a canonical `.index` file from a variety of\nsources. Being so flexible, exactly how a developer decides to store a project's\nmetadata is a largely a matter of taste. But in general there are four overall\napproaches:\n\n1. Specify the metadata in one or more static files, typically a single YAML file.\n2. Specify the metadata using microformats in a project's README file.\n3. Construct the metadata via a Ruby DSL, customizing the generation in any way.\n\nThe first approach is a great option in the it is the easiest. One can quickly\nput together a YAML document covering a project's metadata. Since Indexer is\nvery flexible in it's parsing of the YAML, it really is a quick and user-friendly\nway to go. Typically this file will be called `Index.yml`, but there is no name\nrequirement. In fact, Indexer will also let you split the metadata up over\nmultiple files, and can even go as far as using a *file store*,  which is\na directory of files, one for each field.\n\nThe second choice is, in many respects, the nicest because it does not require any\nadditional files be added to a project and it helps to ensure a good README file.\nOn the downside, it may require some HTML be hand-coded into the README. If your\nREADME's markup format has a sexy syntax for microformats, this approach rocks.\nOtherwise, another approach is probably the better choice.\n\nThe last approach provides maximum flexibility. Using the Ruby DSL one can literally\nscript the metadata, which means it can come from anywhere at all. For example,\nyou might want to pull the project's version from the `lib/project/version.rb`\nfile, i.e. Bundler style. The DSL is as intuitive and as flexible as using plain\nYAML, so it's nearly as easy to take this approach. By convention this file is\ncalled `Indexfile` or `Index.rb`, but it too can be any file path one prefers.\n\nOn the Indexer wiki you can find detailed tutorials on a variety of setups,\nalong with their pros and cons and various tip and tricks.\n\n### [Usage Example](#example)\n\nAs an example of getting started, lets say we want to customize our index\nmetadata via a YAML file, but we want to keep the version information is\na separate `VERSION` file. That's a common layout so Indexer is designed\nto handle it out of the box. First create the `VERSION` file.\n\n    $ echo '0.1.0' \u003e VERSION\n\nNext we need our YAML file. Indexer makes out life easier by offering us some\ntemplate generation for common approaches. In this case we use the `-g/--generate`\ncommand option, specifying that we want an `Index.yml` file.\n\n    $ index --generate Index.yml\n\nNow we can edit the `Index.yaml` file to suite our project.\n\n    $ vim Index.yml\n\nOnce we have the source files setup, its easy to build the canonical `.index`\nfile using the `index` command. We simply issue the `index` command with\nthe `-u/--using` command option:\n\n    $ index --using VERSION Index.yml\n\nIndexer will utilize both sources and create the `.index` file.\n\nOver time project metadata tends to evolve and change. To keep the canonical\n`.index` file up to date simply call the `index` command without any options.\n\n    $ index\n\nBy default the `.index` file will not be updated if it has a modification time\nnewer than its source files. If need be, use the `-f/--force` option to\noverride this.\n\nThat's the quick \"one two\" of getting started with Indexer. For more information,\nsee the Wiki, API documentation, QED specifications and the Manpages.\n\n\n## [Resources](#resources)\n\n* [Website](http://rubyworks.github.com/indexer)\n* [Source Code](http://github.com/rubyworks/indexer) (Github)\n* [API Guide](http://rubydoc.info/gems/indexer/frames)\n* [Master Git Repo](http://github.com/rubyworks/indexer/indexer.git)\n\n\n## [Requirements](#requirements)\n\n* [nokogiri](http://nokogiri.org/) 1.5+\n* [kramdown](http://kramdown.rubyforge.org/) 0.14+\n* [redcarpet](https://github.com/vmg/redcarpet) 2.0+ (optional)\n* [qed](http://rubyworks.github.com/qed/) 2.9+ (test)\n* [ae](http://rubyworks.github.com/ae/) (test)\n\n\n## [Authors](#authors)\n\n\u003cul\u003e\n\u003cli class=\"iauthor vcard\"\u003e\n  \u003cdiv class=\"nickname\"\u003etrans\u003c/div\u003e\n  \u003cdiv\u003e\u003ca class=\"email\" href=\"mailto:transfire@gmail.com\"\u003etransfire@gmail.com\u003c/a\u003e\u003c/div\u003e\n  \u003cdiv\u003e\u003ca class=\"url\" href=\"http://trans.gihub.com/\"\u003ehttp://trans.github.com/\u003c/a\u003e\u003c/div\u003e\n\u003c/li\u003e\n\u003cli class=\"iauthor vcard\"\u003e\n  \u003cdiv class=\"nickname\"\u003epostmodern\u003c/div\u003e\n  \u003cdiv\u003e\u003ca class=\"url\" href=\"http://postmodern.github.com/\"\u003ehttp://postmodern.github.com/\u003c/a\u003e\u003c/div\u003e\n\u003c/li\u003e\n\u003c/ul\u003e\n\n\n## [Copyrights](#copyrights)\n\nIndexer is copyrighted open-source software.\n\n**\u0026copy; 2012 Rubyworks**\n\nIt can be modified and redistributed in accordance with the terms\nof the [BSD-2-Clause](http://www.spdx.org/licenses/BSD-2-Clause) license.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubyworks%2Findexer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frubyworks%2Findexer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frubyworks%2Findexer/lists"}