{"id":24685327,"url":"https://github.com/mattyod/matic","last_synced_at":"2025-06-24T04:33:06.516Z","repository":{"id":3270109,"uuid":"4309438","full_name":"mattyod/matic","owner":"mattyod","description":"Automated HTML documentation for JSON schemas","archived":false,"fork":false,"pushed_at":"2016-12-14T12:27:28.000Z","size":174,"stargazers_count":176,"open_issues_count":3,"forks_count":33,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-03-24T15:48:19.413Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/mattyod.png","metadata":{"files":{"readme":"README-old.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-05-12T20:21:12.000Z","updated_at":"2024-02-27T16:56:40.000Z","dependencies_parsed_at":"2022-07-07T18:22:31.044Z","dependency_job_id":null,"html_url":"https://github.com/mattyod/matic","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattyod%2Fmatic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattyod%2Fmatic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattyod%2Fmatic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattyod%2Fmatic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mattyod","download_url":"https://codeload.github.com/mattyod/matic/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248143055,"owners_count":21054696,"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":"2025-01-26T15:18:36.033Z","updated_at":"2025-04-10T02:20:39.405Z","avatar_url":"https://github.com/mattyod.png","language":"JavaScript","funding_links":[],"categories":["JSON Schema Tools"],"sub_categories":[],"readme":"# Matic [![Build Status](https://secure.travis-ci.org/mattyod/matic.png?branch=master)](http://travis-ci.org/mattyod/matic)\nA Node.js build tool for generating HTML documentation from JSON schemas.\n\nMatic is currently in Alpha state and whilst usable for most use cases still lots of work remain as development continues. You are encouraged to fork the repo should you wish to contribute to the code and bug reports or suggestions will be attended to in the issue queue.\n\nCurrent development was based on the [draft JSON schema 03](http://tools.ietf.org/html/draft-zyp-json-schema-03) specification and support for any follow up specifications will be ported as they become available.\n\n## Installation\nUse NPM to install globally:\n\n    $ npm install -g matic\n\nA sure indication that matic is installed and operational, which also retrieves the current version number, is to run the command:\n\n    $ matic -v\n\n## Building documentation\nFrom the root of your project folder simply run:\n\n    $ matic\n\n### Example projects\nThere are three example projects available, which are full project folders not yet built with Matic, to aid as examples of how to structure your project folder to work with Matic: \n\n  * [very simple example](https://github.com/mattyod/matic-very-simple-example). Which contains one schema file and one template file. [Very simple generated mark up](http://mattyod.github.com/matic-very-simple-example/).\n  * [simple example](https://github.com/mattyod/matic-simple-example). Which contains one schema file and a more structured template set-up with includes and mixins. [Simple generated mark up](http://mattyod.github.com/matic-simple-example/).\n  * [example](https://github.com/mattyod/matic-example). Which contains a schema and a sub schema as well as a more structured template set-up with includes and mixins. [Generated mark up](http://mattyod.github.com/matic-example/).\n\nA typical layout using default settings:\n\n```\n|____config.json\n|____schemas\n| |____my-awesome-schema.json\n|____templates\n| |____default.jade\n|____web\n```\n\nEssentially you will need \n * a folder with at least one schema document \n * a folder with at least one template file\n * an optional config file for custom settings\n\nThe default global configuration looks for a main template with filename `default.jade` which can be customized with a project level config file, ([see below](#setting-config-options)).\n\nBy default Matic will use your template(s) and schema(s) to generate a set of HTML files into a folder named `web`, this can also be modified through the local config file.\n\n## Setting config options\nVarious default settings are configured through Matic's global config file. These settings can be modified on a per project basis by providing a custom `config.json` file located at the root of the project folder.\n\nThe following parameters are configurable, default values in brackets:\n\n### Source [./schemas/]\nThe source folder is where Matic will look for JSON schema documents. These files can have any name with the `.json` extension.\n\nExample:\n```json\n{\"source\": \"./schemas/\"}\n```\n\n### Target [./web/]\nThis is the output folder where Matic will generate the resulting HTML files. This folder will be created automatically, if it does not exist.\n\nExample:\n```json\n{\"target\": \"./web/\"}\n```\n\n### Suffix [.html]\nSuffix to apply to generated files. As an example you might change this to '.md' and generate markdown pages for a github wiki.\n\nExample:\n```json\n{\"suffix\": \".html\"}\n```\n\n### Template\nThis is an object containing details of the templating language which you intend Matic to use to generate the HTML output. Please note only support for Jade has been tested to date, although it should work equally well with other libraries which implement the `compile()` and `render()` methods. If you do happen to have the opportunity to test Matic with an alternative provider, please report back with your findings.\n\nThe template configuration object has the following settings:\n\n#### Folder [true]\nBoolean flag that indicates whether Matic should map multiple template files to corresponding schemas. Significantly this allows for a greater verbosity when documenting more than one schema as each template can contain any extra explanations or examples specific to the relevant schema.\n\nSo for example, when set to true, a folder structure such as:\n\n```\n|____templates\n| |____one.jade\n| |____two.jade\n|____schemas\n| |____one.json\n| |____two.json\n```\n\nWill generate an output folder such as:\n\n```\n|____web\n| |____one.html\n| |____two.html\n```\n\nWhere both schemas have been rendered through their corresponding templates.\n\n**N.B.** It is not necessary to specify a file attribute ([see below](#file-default)) within the templates object if mapping a folder like this, however, if there are schemas that do not map directly to template files, i.e. have the same name, Matic will attempt to use the file specified by the file attribute as a default template.\n\nSimilarly if the folder attribute is set to false Matic will just map all schemas to the file specified by the 'file' attribute, which is 'default' by default. Each generated file will take the name of it's schema so a starting structure such as:\n\n```\n|____templates\n| |____default.jade\n|____schemas\n| |____one.json\n| |____two.json\n```\n\nWill generate the same output web folder as above but both output files will have been passed through default.jade schema.\n\n#### Path [./templates/]\nThe path to your template files folder.\n\n#### File [default]\nThe name of your primary template file which should be at the top level of the templates folder specified in the 'path' attribute.\n\n#### Lib [jade]\nName of the template library to use. **Note:** Matic will assume that the template files have the same extension. i.e. default.jade\n\nExample:\n```json\n\"template\": {\n  \"folder\": true,\n  \"path\": \"./templates/\",\n  \"file\": \"default\",\n  \"lib\": \"jade\"\n}\n```\n\nIn this example Matic will expect to find a file named default.jade located in the templates folder at the root of your project.\n\n### Assets [ ]\nAn array of files or folders to be copied into the target build folder. There are no resources referenced by default, you will need to add your own config.json file to the project root if you want Matic to copy additional files and/or folders during build. The original resources will remain unchanged.\n\nExample:\n```json\n{\"assets\": [\"css\", \"js\"]}\n```\n\nThis example instructs Matic to copy two folders named `css` and `js` into the target build folder. Copying is done recursively so includes all files and sub folders.\n\n## Licence\n\n[MIT](https://raw.github.com/mattyod/matic/master/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattyod%2Fmatic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattyod%2Fmatic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattyod%2Fmatic/lists"}