Projectz

Stop wasting time syncing and updating your project's README and Package Files!

Here's some of the things it can do:

• Keep your projects data files synchronised appropriately, supports:
  • package.json
  • bower.json
  • component.json
  • jquery.json
• Create beautiful standardised readme files that stay in sync with your data files, supports:
  • README.md
  • CONTRIBUTING.md
  • LICENSE.md
  • BACKERS.md
  • HISTORY.md
• Automatic injection of the appropriate installation methods, supports:
  • NPM
  • Browserify
  • Ender
  • Component
  • Bower
• Automatic injection of the appropriate badges for your project, supports:
  • Development Badges
    • NPM Package Version
    • NPM Package Downloads
    • Waffle.io Stories
    • Travis CI Build Status
    • David DM Dependencies, and Dev Dependencies
    • Coveralls
    • Sauce Labs Browser Matrix
  • Donation Badges
    • Gratipay
    • Flattr
    • Paypal
    • BitCoin URL
    • Wishlist URL
• Automatic injection of your license information, supports:
  • MIT
  • CC-BY-4.0
  • Dual Licenses
  • More to come
• Keep your data and readme files up to date with remote data, supports:
  • Pulling in your latest contributors from GitHub
  • Pulling in your latest financial backers from Flattr, etc (coming soon)

Install

NPM

• Use: require('projectz')
• Install: npm install --save projectz

Running Projectz

Directly

Once installed locally, you can compile your project using projectz by running the following in your terminal:

node ./node_modules/projectz/bin/projectz compile 

Automatically

To make projectz more automatic, we recommended adding the direct command to your build tool.

If you don't use a build tool, but do use npm, then you can add the following to your project's package.json file:

{
  "scripts": {
    "compile": "node ./node_modules/projectz/bin/projectz compile",
    "posttest": "node ./node_modules/projectz/bin/projectz compile"
  }
}

The compile script here lets you use npm run-script compile to compile your project with projectz.

The posttest script here automaticaly compiles your project with projectz after your tests have successfully completed, providing you use npm test to run your tests. This is a great place to put projectz as projectz only updates meta documents so won't affect your test, and will always run before a publish.

Configuring Projectz

Data Files

Projectz helps you maintain the following data files:

• package.json
• bower.json
• component.json
• jquery.json

It does this by reading them, combining their data in memory, and then outputting the appropriate fields and over-rides for each file.

Each file can serve as the master meta data file, however you can also define a projectz.cson CSON file that you can use if you'd like to have the benefit of comments, optional commas, multiline strings, etc for your primary meta data file.

The special fields are as so:

{
	# Project's human readable name
	title: "Projectz"

	# Project slug name
	name: "projectz"

	# Project GitHub repository full name
	# If `repository` is set, or if `homepage` is a GitHub URL, we set this automatically
	repo: "bevry/projectz"

	# Project's homepage URL
	# If `repo`, `repository`, or `demo` is set, we set this automatically
	homepage: "https://github.com/bevry/projectz"

	# Project's demo URL
	# If `homepage` or  is set, we set this automatically
	demo: "https://github.com/bevry/projectz"

	# Project description
	description: "Stop wasting time syncing and updating your project's README and Package Files!"

	# Project keywords
	# Can be an array or CSV string
	keywords: "a, b, c"

	# Project's author details
	# Can be an array or CSV string
	authors: ["2013+ Bevry Pty Ltd <us@bevry.me> (http://bevry.me)"]
	author: null

	# Maintainers
	# Can be an array or CSV string
	maintainers: ["Benjamin Lupton (b@lupton.cc) (http://bevry.me)"]
	maintainer: null

	# Sponsors
	# Can be an array or CSV string
	sponsors: ["Benjamin Lupton (b@lupton.cc) (http://bevry.me)"]

	# Contributors
	# Pulled in automatically from the GitHub Repository API and the GitHub Repository's `package.json` file
	contributors: null

	# Project's license details
	# Can be an array or CSV string
	license: "MIT"  # {type:"MIT", url:"http://..."}
	licenses: null

	# Project's repository details
	# If `repo` is set, or if `homepage` is a GitHub URL, we set this automatically
	repository:
		type: "git"
		url: "https://github.com/bevry/projectz.git"

	# Project's repository details
	# If `repo` is set, or if `homepage` is a GitHub URL, we set this automatically
	bugs:
		url: "https://github.com/bevry/projectz/issues"

	# Whether the project can run on the client-side in web browsers
	# If the component or bower package information is set, then this becomes true automatically
	browsers: true

	# Project's badges for use in the readme files
	badges:
		# Travis CI Badge
		# If not set, fallbacks to true if the `.travis.yml` file exists
		travis: true

		# NPM Version Badge
		# If not set, fallbacks to true if the `package.json` file exists
		npm: true

		# NPM Downloads Badge
		# If not set, fallbacks to true if the `package.json` file exists
		npmdownloads: true

		# David DM Dependency Badge
		# If not set, fallbacks to true if the `package.json` file exists
		# Will only run if dependencies is set
		david: true

		# David DM Dev Dependency Badge
		# If not set, fallbacks to the David DM Dependency Badge value
		# Will only run if dev dependencies is set
		daviddev: true

		# Waffle.io Badge
		# If a string is provided, that will be used as the GitHub issue queue
		# label. Otherwise, the label will default to "ready".
		waffleio: true

		# Coveralls.io Badge
		# If a string is provided, that will be used as the label for the badge.
		# Otherwise, the label will default to "Coverage Status".
		coveralls: true

		# Sauce Labs Browser Matrix Badge
		# If a string is provided, that will be used as the user id for the badge.
		saucebm: "user id"
		
		# Gratipay Badge
		gratipay: "balupton"

		# Flattr Badge
		flattr: "344188/balupton-on-Flattr"

		# Paypal Badge
		paypal: "QB8GQPZAH84N6"

		# BitCoin Badge
		bitcoin: "https://coinbase.com/checkouts/9ef59f5479eec1d97d63382c9ebcb93a"

		# Wishlist Badge
		wishlist: "http://amzn.com/w/2F8TXKSNAFG4V"

}

Readme Files

Projectz helps you maintain the following readme files:

• README.md
• CONTRIBUTING.md
• LICENSE.md
• BACKERS.md
• HISTORY.md

It does this by reading them, and replacing comment tags with the approriate data.

The following comment tags are supported:

• <!-- TITLE --> — outputs the package's title field
• <!-- BADGES --> — outputs the badges you have enabled from your package's badges field
• <!-- DESCRIPTION --> — outputs the package's description field
• <!-- INSTALL --> — supports installation instructions for:
  • npm (if the package.json file exists)
  • browserify, ender (if the package.json file exists and the browsers field is truthy)
  • bower (if the bower.json file exists)
  • component (if the component.json file exists)
• <!-- HISTORY --> — outputs a link to the HISTORY.md file
• <!-- CONTRIBUTE --> — outputs a link to the CONTRIBUTE.md file
• <!-- BACKERS --> — outputs the information from the sponsors field, as well as any sponsor type badges
• <!-- LICENSE --> — outputs a summary of the license information, and a link to the LICENSE.md

As well as these comment tags for updating entire files:

• <!-- LICENSEFILE --> — outputs the complete license information
• <!-- BACKERSFILE --> — same as <!-- BACKERS --> but made for an individual file instead

As an example, here is a a basic README.md file:

<!-- TITLE -->
<!-- BADGES -->
<!-- DESCRIPTION -->
<!-- INSTALL -->

## Usage
Usage instructions go here

<!-- HISTORY -->
<!-- CONTRIBUTE -->
<!-- BACKERS -->
<!-- LICENSE -->

History

Discover the change history by heading on over to the HISTORY.md file.

Contribute

Discover how you can contribute by heading on over to the CONTRIBUTING.md file.

Backers

Maintainers

These amazing people are maintaining this project:

• Benjamin Lupton b@lupton.cc (https://github.com/balupton)
• Rob Loach robloach@gmail.com (https://github.com/RobLoach)

Sponsors

No sponsors yet! Will you be the first?

Contributors

These amazing people have contributed code to this project:

• Benjamin Lupton b@lupton.cc — view contributions
• pflannery — view contributions
• Rob Loach robloach@gmail.com — view contributions
• Zearin — view contributions

Become a contributor!

License

Unless stated otherwise all works are:

• Copyright © 2013+ Bevry Pty Ltd us@bevry.me (http://bevry.me)

and licensed under:

• The incredibly permissive MIT License