{"id":17398438,"url":"https://github.com/vweevers/hallmark","last_synced_at":"2025-09-15T09:41:06.872Z","repository":{"id":32629776,"uuid":"132333349","full_name":"vweevers/hallmark","owner":"vweevers","description":"Markdown Style Guide, with linter and automatic fixer.","archived":false,"fork":false,"pushed_at":"2024-10-08T21:07:53.000Z","size":938,"stargazers_count":39,"open_issues_count":8,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-06T08:43:22.195Z","etag":null,"topics":["documentation","fixer","linter","markdown","remark","tooling"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vweevers.png","metadata":{"files":{"readme":"README.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-05-06T11:46:48.000Z","updated_at":"2025-03-21T01:25:03.000Z","dependencies_parsed_at":"2024-01-15T07:08:59.315Z","dependency_job_id":"40709f75-47c9-4425-b5de-39f2d4e4efb2","html_url":"https://github.com/vweevers/hallmark","commit_stats":{"total_commits":111,"total_committers":3,"mean_commits":37.0,"dds":"0.15315315315315314","last_synced_commit":"c078019a85a21d52cef42edbd3f61e1c3710e421"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vweevers%2Fhallmark","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vweevers%2Fhallmark/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vweevers%2Fhallmark/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vweevers%2Fhallmark/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vweevers","download_url":"https://codeload.github.com/vweevers/hallmark/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247657276,"owners_count":20974344,"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":["documentation","fixer","linter","markdown","remark","tooling"],"created_at":"2024-10-16T14:56:28.418Z","updated_at":"2025-04-07T13:05:16.726Z","avatar_url":"https://github.com/vweevers.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hallmark\n\n\u003e **Markdown Style Guide, with linter and automatic fixer.** :sparkles:\\\n\u003e Powered by [`remark`][remark].\n\n[![npm status](http://img.shields.io/npm/v/hallmark.svg)](https://www.npmjs.org/package/hallmark)\n[![node](https://img.shields.io/node/v/hallmark.svg)](https://www.npmjs.org/package/hallmark)\n[![Test](https://img.shields.io/github/actions/workflow/status/vweevers/hallmark/test.yml?branch=main\u0026label=test)](https://github.com/vweevers/hallmark/actions/workflows/test.yml)\n[![JavaScript Style Guide](https://img.shields.io/badge/standard-informational?logo=javascript\\\u0026logoColor=fff)](https://standardjs.com)\n[![Markdown Style Guide](https://img.shields.io/badge/hallmark-informational?logo=markdown)](https://github.com/vweevers/hallmark)\n[![Common Changelog](https://common-changelog.org/badge.svg)](https://common-changelog.org)\n\n## Why\n\nThis module saves you time in three ways:\n\n- **No configuration.** The easiest way to enforce markdown code quality in your project. No decisions to make. No `remark` plugins to manage.\n- **Automatically format markdown.** Run `hallmark fix` to format markdown, wrap GitHub issues and usernames in links, autocomplete a `CHANGELOG.md` following [Common Changelog](https://common-changelog.org) and more.\n- **Catch style issues \u0026 mistakes early.** Save code review time by eliminating back-and-forth between reviewer \u0026 contributor.\n\n## Quick Start\n\nLint `*.md` files:\n\n```\nhallmark\n```\n\nFix markdown files in place:\n\n```\nhallmark fix\n```\n\nFix custom files:\n\n```\nhallmark fix CHANGELOG.md docs/*.md\n```\n\nAdd new minor version or existing version to changelog, optionally without content:\n\n```\nhallmark cc add minor\nhallmark cc add 4.2.0 --no-commits\n```\n\n## What You Might Do\n\nAdd `hallmark` to your `package.json`:\n\n```json\n{\n  \"name\": \"my-awesome-package\",\n  \"devDependencies\": {\n    \"hallmark\": \"^2.0.0\"\n  },\n  \"scripts\": {\n    \"test\": \"hallmark \u0026\u0026 node my-tests.js\"\n  }\n}\n```\n\nMarkdown is then checked automatically when you run `npm test`:\n\n```\n$ npm test\nREADME.md:5:3\n  ⚠️  5:3  Found reference to undefined definition  remark-lint:no-undefined-references\n\n  1 warning\n```\n\n## Requirements\n\n- The working directory must be a git repository\n- It must either contain a `package.json` with a [`repository`](https://docs.npmjs.com/files/package.json#repository) property, or have a git `origin` remote\n\n## Rules\n\n- [Use `-` as marker for bullets of items in unordered lists](https://www.npmjs.com/package/remark-lint-unordered-list-marker-style) (`- item`)\n- [Use `_` as marker for emphasis](https://www.npmjs.com/package/remark-lint-emphasis-marker) (`_emphasis_`)\n- [Use `*` as marker for strong](https://www.npmjs.com/package/remark-lint-strong-marker) (`**strong**`)\n- [Use `x` as marker for checkboxes](https://www.npmjs.com/package/remark-lint-checkbox-character-style) (`- [x] item`)\n- [Use backtick as marker for fenced code block](https://www.npmjs.com/package/remark-lint-fenced-code-marker)\n- [Always use fences for code blocks](https://www.npmjs.com/package/remark-lint-code-block-style)\n- [Use `---` for thematic breaks](https://www.npmjs.com/package/remark-lint-rule-style)\n- [Insert links to GitHub issues, PRs and usernames](https://www.npmjs.com/package/remark-github) (not linted)\n- [Collapse a Table of Contents if it exists](https://www.npmjs.com/package/remark-collapse) (not linted)\n- [End file with newline](https://www.npmjs.com/package/remark-lint-final-newline)\n- No dead links, references and definitions:\n  - [No dead internal links](https://www.npmjs.com/package/remark-validate-links)\n  - [No references to undefined definitions](https://www.npmjs.com/package/remark-lint-no-undefined-references)\n  - [No unused definitions](https://www.npmjs.com/package/remark-lint-no-unused-definitions)\n  - [No duplicate definitions](https://www.npmjs.com/package/remark-lint-no-duplicate-definitions)\n  - [Definition labels must be lowercase](https://www.npmjs.com/package/remark-lint-definition-case)\n- No more spaces than needed:\n  - [Indent list items with a single space (`-  item`)](https://www.npmjs.com/package/remark-lint-list-item-indent)\n  - [Indent blockquote content with a single space](https://www.npmjs.com/package/remark-lint-blockquote-indentation)\n  - [Checkboxes must be followed by a single space](https://www.npmjs.com/package/remark-lint-checkbox-content-indent)\n  - [No indentation before list item bullets](https://www.npmjs.com/package/remark-lint-list-item-bullet-indent)\n  - [No unneeded padding around heading content](https://www.npmjs.com/package/remark-lint-no-heading-content-indent)\n  - [No more than two spaces to create a hard break](https://www.npmjs.com/package/remark-lint-hard-break-spaces)\n  - [No inline padding between markers and content (`_ content _`)](https://www.npmjs.com/package/remark-lint-no-inline-padding)\n- Parsable literal URLs:\n  - [No literal URLs without angle-brackets](https://www.npmjs.com/package/remark-lint-no-literal-urls)\n  - [No angle-bracketed links (`\u003curl\u003e`) without protocol](https://www.npmjs.com/package/remark-lint-no-auto-link-without-protocol)\n- [No blank lines without markers (`\u003e`) in a blockquote](https://www.npmjs.com/package/remark-lint-no-blockquote-without-marker)\n- Tables:\n  - [Table cells must be padded](https://www.npmjs.com/package/remark-lint-table-cell-padding) ([#16](https://github.com/vweevers/hallmark/issues/16))\n  - [Table rows must be fenced with pipes](https://www.npmjs.com/package/remark-lint-table-pipes)\n\n## Usage\n\n`hallmark [command] [options]`\n\nLint or fix files in the current working directory. The default command is `lint`.\n\nOptions:\n\n- `--ignore / -i \u003cfile\u003e`: file or glob pattern to ignore. Repeat to specify multiple (e.g. `-i a.md -i docs/*.md`). Can also be configured via [Package Options](#package-options).\n- `--help`: print usage and exit\n- `--version`: print version and exit\n- `--report \u003creporter\u003e`: see [Reporters](#reporters)\n- `--[no-]color`: force color in report (detected by default)\n- `--fix`: backwards-compatible alias for fix command\n- `--verbose`: enable verbose output\n\n### Commands\n\n#### `lint [file...]`\n\nLint markdown files. By default `hallmark` includes files matching `*.md`. To override this, provide one or more file arguments which can be file paths or glob patterns. Files matching `.gitignore` patterns are ignored. To ignore additional files, use the `--ignore / -i` option.\n\n#### `fix [file...]`\n\nFix markdown files in place. The optional `file` argument is the same as on `lint`.\n\n#### `cc add \u003ctarget...\u003e`\n\nAdd release(s) to `CHANGELOG.md` and populate it with commits. If no `CHANGELOG.md` file exists then it will be created. The `target` argument must be one of:\n\n- A release type: `major`, `minor`, `patch`, `premajor`, `preminor`, `prepatch`, `prerelease`\n  - These take the current version from the semver-latest tag, release or `package.json` (whichever is greatest if found) and bump it\n  - The `major` type bumps the major version (for example `2.4.1 =\u003e 3.0.0`); `minor` and `patch` work the same way.\n  - The `premajor` type bumps the version up to the next major version and down to a prerelease of that major version; `preminor` and `prepatch` work the same way.\n  - The `prerelease` type works the same as `prepatch` if the current version is a non-prerelease. If the current is already a prerelease then it's simply incremented (for example `4.0.0-rc.2` to `4.0.0-rc.3`).\n- A [semver-valid](https://semver.org/) version like 2.4.0.\n\nIf the (resulting) version is greater than the current version then commits will be taken from the semver-latest tag until HEAD. I.e. documenting a new release before it's git-tagged. If the version matches an existing tag then a release will be inserted at the appriopriate place, populated with commits between that version's tag and the one before it. I.e. documenting a past release after it's git-tagged. If the version equals `0.0.1` or `1.0.0` and zero versions exist, then a [notice](https://common-changelog.org/#23notice) will be inserted (rather than commits) containing the text `:seedling: Initial release.`.\n\nAdditional options for this command:\n\n- `--no-commits`: create an empty release.\n\nMultiple targets can be provided, in no particular order. For example `hallmark cc add 1.1.0 1.2.0` which acts as a shortcut for `hallmark cc add 1.1.0 \u0026\u0026 hallmark cc add 1.2.0`.\n\nWorks best on a linear git history without merge commits. If `hallmark` encounters other tags in the commit range it will stop there and not include further (older) commits.\n\nThe `cc add` command also fixes markdown (both existing content and generated content) but only in `CHANGELOG.md`. After you tweak the release following [Common Changelog](https://common-changelog.org) you may want to run `hallmark fix`.\n\nGit [trailers](https://git-scm.com/docs/git-interpret-trailers) (\"lines that look similar to RFC 822 e-mail headers, at the end of the otherwise free-form part of a commit message\") can provide structured information to the generated changelog. The following trailer keys are supported (case-insensitive):\n\n- `Category`: one of `change`, `addition`, `removal`, `fix`, or `none`. If `none` then the commit will be excluded from the changelog. If not present then the change will be listed under Uncategorized and will require manual categorization.\n- `Notice`: a [notice](https://common-changelog.org/#23-notice) for the release. If multiple commits contain a notice, they will be joined as sentences (i.e. ending with a dot) separated by a space.\n- `Ref`, `Refs`, `Fixes`, `Closes` or `CVE-ID`: a numeric reference in the form of `#N`, `PREFIX-N` or `CVE-N-N` where `N` is a number and `PREFIX` is at least 2 letters. For example `#123`, `GH-123`, `JIRA-123` or `CVE-2024-123`. Can be repeated, either with multiple trailer lines or by separating references with a comma - e.g. `Ref: #1, #2`. Non-numeric references are ignored.\n- `Co-Authored-By`: co-author in the form of `name \u003cemail\u003e`. Can be repeated.\n\nFor example, the following commit (which has Bob as git author, let's say):\n\n```\nBump math-utils to 4.5.6\n\nRef: JIRA-123\nCategory: change\nCo-Authored-By: Alice \u003calice@example.com\u003e\n```\n\nTurns into:\n\n```md\n## Changed\n\n- Bump math-utils to 4.5.6 (d23ba8f) (JIRA-123) (Bob, Alice)\n```\n\n#### `cc init`\n\nCreate a `CHANGELOG.md` from scratch. Inserts releases for every (semver-valid) git tag and then populates them with commits. If no git tags exist then the resulting `CHANGELOG.md` will merely have a `# Changelog` heading, without releases.\n\nAdditional options for this command:\n\n- `--no-commits`: create empty releases\n- `--gte \u003cversion\u003e`: only include versions greater than or equal to this version\n- `--lte \u003cversion\u003e`: only include versions less than or equal to this version.\n\n## Package Options\n\nYou can add a `hallmark` object to your `package.json` with additional configuration. For example:\n\n```json\n{\n  \"name\": \"my-awesome-package\",\n  \"hallmark\": {\n    \"ignore\": [\n      \"CONTRIBUTING.md\"\n    ]\n  }\n}\n```\n\nAlternatively, for use in non-node projects, place a `.hallmarkrc` file in the working directory or any of its parent directories:\n\n```json\n{\n  \"ignore\": [\n    \"CONTRIBUTING.md\"\n  ]\n}\n```\n\n### `ignore`\n\nA string or array of files to ignore. Merged with `--ignore / -i` if any.\n\n### `autolinkReferences`\n\nAutolink custom references [like GitHub Pro](https://docs.github.com/en/free-pro-team@latest/github/administering-a-repository/configuring-autolinks-to-reference-external-resources) does. Must be an object with a `prefix` and `url` (if `autolinkReferences` is not set, this feature does nothing). For example, given:\n\n```json\n{\n  \"autolinkReferences\": {\n    \"prefix\": \"JIRA-\",\n    \"url\": \"https://example.atlassian.net/browse/JIRA-\u003cnum\u003e\"\n  }\n}\n```\n\nThen `hallmark fix` will transform:\n\n```md\n### Fixed\n\n- Prevent infinite loop (JIRA-4275)\n```\n\nTo:\n\n```md\n### Fixed\n\n- Prevent infinite loop ([JIRA-4275](https://example.atlassian.net/browse/JIRA-4275))\n```\n\nWhile `hallmark lint` will warn about unlinked references.\n\n### `changelog`\n\nAn object containing options to be passed to [`remark-common-changelog`](https://github.com/vweevers/remark-common-changelog):\n\n- `submodules` (boolean): enable experimental git submodule support. Will (upon encountering new or empty changelog entries) collect commits from submodules and list them in the changelog as `\u003csubmodule\u003e: \u003cmessage\u003e`.\n\n### `validateLinks`\n\nBoolean. Set to `false` to skip validating links. Useful when a markdown file uses HTML anchors, which not are not recognized as links. A temporary option until we decide whether to allow and parse those.\n\n### `paddedTable`\n\nBoolean. Set to `false` to keep markdown tables compact. A temporary option until we decide on and are able to lint a style ([`3210a96`](https://github.com/vweevers/hallmark/commit/3210a96)).\n\n### `plugins`\n\nAn array of extra plugins, to be applied in both lint and fix mode.\n\n### `fixers`\n\nAn array of extra plugins, to be applied in fix mode.\n\n## Reporters\n\nThe default reporter is [`vfile-reporter-shiny`](https://github.com/vweevers/vfile-reporter-shiny). Various other reporters are available:\n\n- [`vfile-reporter`](https://npmjs.org/package/vfile-reporter)\n- [`vfile-reporter-json`](https://npmjs.org/package/vfile-reporter-json)\n- [`vfile-reporter-pretty`](https://npmjs.org/package/vfile-reporter-pretty)\n\nTo use a custom reporter first install it with [npm](https://npmjs.org):\n\n```\nnpm i vfile-reporter-json --save-dev\n```\n\nThen pass it to `hallmark` with or without options:\n\n```\nhallmark --report json\nhallmark --report [ json --pretty ]\n```\n\nIn the programmatic API of `hallmark` (which is not documented yet) the reporter can also be disabled by passing `{ report: false }` as the options.\n\n## Install\n\nWith [npm](https://npmjs.org) do:\n\n```\nnpm install hallmark --save-dev\n```\n\n## License\n\n[GPL-3.0](LICENSE) © 2018-present Vincent Weevers.\n\n[remark]: https://www.npmjs.org/package/remark\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvweevers%2Fhallmark","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvweevers%2Fhallmark","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvweevers%2Fhallmark/lists"}