From 533813b3dbe7d3687733046822c549e8b23d5dc2 Mon Sep 17 00:00:00 2001 From: Dura Date: Thu, 2 Aug 2018 15:43:21 -0600 Subject: [PATCH] docs: Format config docs with examples and defaults to be understood more easily (#107) User like myself don't understand how to provide custom templates to certain config options. --- .all-contributorsrc | 12 +++++- README.md | 99 +++++++++++++++++++++++++++------------------ 2 files changed, 71 insertions(+), 40 deletions(-) diff --git a/.all-contributorsrc b/.all-contributorsrc index 0e84f29..499d6aa 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -224,6 +224,16 @@ "contributions": [ "doc" ] + }, + { + "login": "chris-dura", + "name": "Dura", + "avatar_url": "https://avatars3.githubusercontent.com/u/3680914?v=4", + "profile": "https://github.com/chris-dura", + "contributions": [ + "doc" + ] } - ] + ], + "repoType": "github" } diff --git a/README.md b/README.md index e78221a..4c98121 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ [![version][version-badge]][package] [![downloads][downloads-badge]][downloads] [![MIT License][license-badge]][license] -[![All Contributors](https://img.shields.io/badge/all_contributors-23-orange.svg?style=flat-square)](#contributors) +[![All Contributors](https://img.shields.io/badge/all_contributors-24-orange.svg?style=flat-square)](#contributors) [![PRs Welcome][prs-badge]][prs] [![Code of Conduct][coc-badge]][coc] [![Watch on GitHub][github-watch-badge]][github-watch] [![Star on GitHub][github-star-badge]][github-star] @@ -32,7 +32,6 @@ specification for your GitHub or GitLab repository. - - [Installation](#installation) - [Usage](#usage) - [Generating the contributors list](#generating-the-contributors-list) @@ -115,27 +114,27 @@ Where `username` is the user's GitHub or Gitlab username, and `contribution` is `,`-separated list of ways to contribute, from the following list ([see the specs](https://github.com/kentcdodds/all-contributors#emoji-key)): -* blog: [📝](# "Blogposts") -* bug: [🐛](# "Bug reports") -* code: [💻](# "Code") -* design: [🎨](# "Design") -* doc: [📖](# "Documentation") -* eventOrganizing: [📋](# "Event Organizing") -* example: [💡](# "Examples") -* financial: [💵](# "Financial") -* fundingFinding: [🔍](# "Funding Finding") -* ideas: [🤔](# "Ideas, Planning, & Feedback") -* infra: [🚇](# "Infrastructure (Hosting, Build-Tools, etc)") -* platform: [📦](# "Packaging/porting to new platform") -* plugin: [🔌](# "Plugin/utility libraries") -* question: [💬](# "Answering Questions") -* review: [👀](# "Reviewed Pull Requests") -* talk: [📢](# "Talks") -* test: [⚠️](# "Tests") -* tool: [🔧](# "Tools") -* translation: [🌍](# "Translation") -* tutorial: [✅](# "Tutorials") -* video: [📹](# "Videos") +- blog: [📝](# 'Blogposts') +- bug: [🐛](# 'Bug reports') +- code: [💻](# 'Code') +- design: [🎨](# 'Design') +- doc: [📖](# 'Documentation') +- eventOrganizing: [📋](# 'Event Organizing') +- example: [💡](# 'Examples') +- financial: [💵](# 'Financial') +- fundingFinding: [🔍](# 'Funding Finding') +- ideas: [🤔](# 'Ideas, Planning, & Feedback') +- infra: [🚇](# 'Infrastructure (Hosting, Build-Tools, etc)') +- platform: [📦](# 'Packaging/porting to new platform') +- plugin: [🔌](# 'Plugin/utility libraries') +- question: [💬](# 'Answering Questions') +- review: [👀](# 'Reviewed Pull Requests') +- talk: [📢](# 'Talks') +- test: [⚠️](# 'Tests') +- tool: [🔧](# 'Tools') +- translation: [🌍](# 'Translation') +- tutorial: [✅](# 'Tutorials') +- video: [📹](# 'Videos') ### Check for missing contributors @@ -158,21 +157,42 @@ can configure how you want `all-contributors-cli` to generate the list. These are the keys you can specify: -* `files`: Array of files to update. Default: `['README.md']` -* `projectOwner`: Name of the user the project is hosted by. Example: - `jfmengels/all-contributors-cli` --> `jfmengels`. Mandatory. -* `projectName`: Name of the project. Example: `jfmengels/all-contributors-cli` - --> `all-contributors-cli`. Mandatory. -* `repoType`: Type of repository. Must be either `github` or `gitlab`. Default: `github`. -* `repoHost`: Points to the repository hostname. Change it if you use a self hosted repository. Default: `https://github.com` if `repoType` is `github`, and `https://gitlab.com` if `repoType` is `gitlab`. -* `types`: Specify custom symbols or link templates for contribution types. Can - override the documented types. -* `imageSize`: Size (in px) of the user's avatar. Default: `100`. -* `contributorsPerLine`: Maximum number of columns for the contributors table. - Default: `7`. -* `contributorTemplate`: Define your own template to generate the contributor - list. -* `badgeTemplate`: Define your own template to generate the badge. +| Option | Description | Example/Default | +| --------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| `projectName` | Mandatory, name of the project. | Example: `all-contributors-cli` | +| `projectOwner` | Mandatory, name of the user the project is hosted by. | Example: `jfmengels` | +| `repoType` | Type of repository. Must be either `github` or `gitlab`. | Default: `github` | +| `repoHost` | Points to the repository hostname. Change it if you use a self-hosted repository. | Default: `https://github.com` if `repoType` is `github`, and `https://gitlab.com` if `repoType` is `gitlab` | +| `files` | Array of files to update. | Default: `['README.md']` | +| `imageSize` | Size (in px) of the user's avatar. | Default: `100` | +| `commit` | Auto-commit badge when adding contributors. | `true` or `false` | +| `contributorsPerLine` | Maximum number of columns for the contributors table. | Default: `7` | +| `badgeTemplate` | Define your own lodash template to generate the badge. | +| `contributorTemplate` | Define your own lodash template to generate the contributor. | +| `types` | Specify custom symbols or link templates for contribution types. Can override the documented types. | + +```json +{ + "projectName": "all-contributors-cli", + "projectOwner": "jfmengels", + "repoType": "github", + "repoHost": "https://github.com", + "files": ["README.md"], + "imageSize": 100, + "commit": false, + "contributorsPerLine": 7, + "badgeTemplate": "[![All Contributors](https://img.shields.io/badge/all_contributors-<%= contributors.length %>-orange.svg?style=flat-square)](#contributors)", + "contributorTemplate": "<%= avatarBlock %>
<%= contributions %>", + "types": { + "custom": { + "symbol": "🔭", + "description": "A custom contribution type.", + "link": "[<%= symbol %>](<%= url %> \"<%= description %>\")," + } + }, + "contributors": [] +} +``` ## Contributors @@ -185,7 +205,8 @@ Thanks goes to these wonderful people | :---: | :---: | :---: | :---: | :---: | :---: | | [
Jerod Santo](https://jerodsanto.net)
[💻](https://github.com/jfmengels/all-contributors-cli/commits?author=jerodsanto "Code") | [
Kevin Jalbert](https://github.com/kevinjalbert)
[💻](https://github.com/jfmengels/all-contributors-cli/commits?author=kevinjalbert "Code") | [
tunnckoCore](https://i.am.charlike.online)
[🔧](#tool-charlike "Tools") | [
Mehdi Achour](https://machour.idk.tn/)
[💻](https://github.com/jfmengels/all-contributors-cli/commits?author=machour "Code") | [
Roy Revelt](https://codsen.com)
[🐛](https://github.com/jfmengels/all-contributors-cli/issues?q=author%3Arevelt "Bug reports") | [
Chris Vickery](https://github.com/chrisinajar)
[💻](https://github.com/jfmengels/all-contributors-cli/commits?author=chrisinajar "Code") | | [
Bryce Reynolds](https://github.com/brycereynolds)
[💻](https://github.com/jfmengels/all-contributors-cli/commits?author=brycereynolds "Code") | [
James, please](http://www.jmeas.com)
[🤔](#ideas-jmeas "Ideas, Planning, & Feedback") [💻](https://github.com/jfmengels/all-contributors-cli/commits?author=jmeas "Code") | [
Spyros Ioakeimidis](http://www.spyros.io)
[💻](https://github.com/jfmengels/all-contributors-cli/commits?author=spirosikmd "Code") | [
Fernando Costa](https://github.com/fadc80)
[💻](https://github.com/jfmengels/all-contributors-cli/commits?author=fadc80 "Code") | [
snipe](https://snipe.net)
[📖](https://github.com/jfmengels/all-contributors-cli/commits?author=snipe "Documentation") | [
Gant Laborde](http://gantlaborde.com/)
[💻](https://github.com/jfmengels/all-contributors-cli/commits?author=GantMan "Code") | -| [
Md Zubair Ahmed](https://in.linkedin.com/in/mzubairahmed)
[📖](https://github.com/jfmengels/all-contributors-cli/commits?author=M-ZubairAhmed "Documentation") [🐛](https://github.com/jfmengels/all-contributors-cli/issues?q=author%3AM-ZubairAhmed "Bug reports") [💻](https://github.com/jfmengels/all-contributors-cli/commits?author=M-ZubairAhmed "Code") [⚠️](https://github.com/jfmengels/all-contributors-cli/commits?author=M-ZubairAhmed "Tests") | [
Divjot Singh](http://bogas04.github.io)
[📖](https://github.com/jfmengels/all-contributors-cli/commits?author=bogas04 "Documentation") | [
João Marques](https://github.com/tigermarques)
[💻](https://github.com/jfmengels/all-contributors-cli/commits?author=tigermarques "Code") [📖](https://github.com/jfmengels/all-contributors-cli/commits?author=tigermarques "Documentation") [🤔](#ideas-tigermarques "Ideas, Planning, & Feedback") | [
Andrew Lisowski](http://hipstersmoothie.com)
[💻](https://github.com/jfmengels/all-contributors-cli/commits?author=hipstersmoothie "Code") [📖](https://github.com/jfmengels/all-contributors-cli/commits?author=hipstersmoothie "Documentation") [⚠️](https://github.com/jfmengels/all-contributors-cli/commits?author=hipstersmoothie "Tests") | [
Xianming Zhong](https://github.com/chinesedfan)
[📖](https://github.com/jfmengels/all-contributors-cli/commits?author=chinesedfan "Documentation") | +| [
Md Zubair Ahmed](https://in.linkedin.com/in/mzubairahmed)
[📖](https://github.com/jfmengels/all-contributors-cli/commits?author=M-ZubairAhmed "Documentation") [🐛](https://github.com/jfmengels/all-contributors-cli/issues?q=author%3AM-ZubairAhmed "Bug reports") [💻](https://github.com/jfmengels/all-contributors-cli/commits?author=M-ZubairAhmed "Code") [⚠️](https://github.com/jfmengels/all-contributors-cli/commits?author=M-ZubairAhmed "Tests") | [
Divjot Singh](http://bogas04.github.io)
[📖](https://github.com/jfmengels/all-contributors-cli/commits?author=bogas04 "Documentation") | [
João Marques](https://github.com/tigermarques)
[💻](https://github.com/jfmengels/all-contributors-cli/commits?author=tigermarques "Code") [📖](https://github.com/jfmengels/all-contributors-cli/commits?author=tigermarques "Documentation") [🤔](#ideas-tigermarques "Ideas, Planning, & Feedback") | [
Andrew Lisowski](http://hipstersmoothie.com)
[💻](https://github.com/jfmengels/all-contributors-cli/commits?author=hipstersmoothie "Code") [📖](https://github.com/jfmengels/all-contributors-cli/commits?author=hipstersmoothie "Documentation") [⚠️](https://github.com/jfmengels/all-contributors-cli/commits?author=hipstersmoothie "Tests") | [
Xianming Zhong](https://github.com/chinesedfan)
[📖](https://github.com/jfmengels/all-contributors-cli/commits?author=chinesedfan "Documentation") | [
Dura](https://github.com/chris-dura)
[📖](https://github.com/jfmengels/all-contributors-cli/commits?author=chris-dura "Documentation") | + This project follows the