0.7.0 released!

[jonschlinkert]

I just merged in the refactor and bumped verb to 0.7.0!!

Getting started with 0.7.0

Highlights

• conflict reporter
• visual diffs
• global data store
• custom template paths/modules

Clear your cache and re-install

Please do the following to use this version to clear out old stuff first, then install the new version:

$ npm cache clean && npm i -g verb-cli

200+ commits

There were a lot of changes on the refactor branch. I'd be surprised if no one has issues, but if you do, I think they will be easier to fix and manage now - mainly since the majority of "bugs" are really not bugs but missing data.

A quick word on that. Lo-dash just throws an error when data is missing, which is easy to see in "top-level" templates, but in nested includes/helpers it gets harder to flesh out the cause sometimes. Here are some things in 0.7.0 to make this easier:

---

New features

First, as a user, you won't ever need to know that verb is using middleware or plugins to accomplish something, but for those who need to create a verbfile.js, or are curious about the inner workings and want to customize, extend, or hack around in verb, here are some details on what's been added:

conflict reporter

See conflicts in the command line!

To output conflicts, just run verb in verbose mode:

$ verb --verbose

Example output

How it works

In verbose mode, the conflict reporter tells you when there are problems with helpers and properties on the context. This works for "renderable" templates, like .verb.md (via a plugin) as well as includes (via a middleware).

For example, currently verb registers both a license data field and a license() helper (I kept the conflict so you can see how the manager works. Don't worry, verb handles it just fine now). Normally, both of these cannot exist on the same object at the same time, so only one of them will be merged onto the context. As a result, the template engine will throw an error when it tries to render either {%= license %} or {%= license() %}.

Solution

The conflict manager plugin detects these conflicts, then it temporarily renames the helper on the fly, re-registers it on the __. object, and deletes it from the data object. That way both the helper and data property will render as expected. (You might be thinking, "why would I have duplicate properties like that?" well, you personally might not, but if you want to use community templates or built-in templates that might have variables you're unaware of, and you want them to "just work", then this is not an uncommon thing...).

---

visual diffs

See the difference between pre-render and post-render templates by running the following in the command line:

$ verb --diff

Example output

global data store

Verb now has an API and CLI for persisting and getting "default" data that can be used across all projects.

set

To set a variable from the command line:

$ verb --set username="jonschlinkert"

get

To get a variable from the command line:

$ verb --get username

Outputs:

$ username = jonschlinkert

del

To delete a variable:

$ verb --del username

Outputs

$ deleted: username

package.json data

Verb already uses the properties in package.json to render templates, but now verb also merges in data from the verb.data object in package.json, allowing you to add custom data to be used specifically for your documentation.

Example

Let's say you want to add your Twitter username to package.json so that it will be used in templates:

{ 
  "name": "my-project",
  "description": "It's awesome, seriously.",

  "verb": {
    "data": {
      "twitter": {"username": "jonschlinkert"}
    }
  }
}

Custom template modules

It has always been possible to use custom templates, but with 0.7.0 it's easier than ever. Just pass the name of the module to use for docs, includes or badges, and it verb will store the names of these modules globally and look for them in each project (or fallback to the defaults if it can't find them).

How to define a custom template module

To define a custom badges module or directory, run the following in the command line:

$ verb --set badges="my-badge-templates"

To define a custom includes module or directory, run the following in the command line:

$ verb --set includes="my-include-templates"

To define a custom docs module or directory, run the following in the command line:

$ verb --set docs="my-docs-templates"

To load your own badge te

(TBC)

[mightyiam]

Awesome. I'm going to use verb so much.

[mightyiam]

Thank you, @jonschlinkert

[jonschlinkert]

👍 hopefully this addresses issues you've had!

[mightyiam]

My package.json has a copyright property, which is a string.

{%= copyright %} resolves to an object, instead of my string from package.json.

[jonschlinkert]

should be fixed by:

• f88762f, and
• helpers/helper-copyright@6e1ecd4

[stefanwalther]

Just great, thx!!!

[stefanwalther]

Do you have an example for verb --set includes="my-include-templates" ...?

Tried it both, with a local module and a path following the example of readme-includes, but didn't succeed, always get:

async-helper-base: {%= include("extension-install") %} error: %j TypeError: Cannot read property 'render' of null

But settings in the app seems to be correct:

 store:
   { name: 'verb',
     path: 'C:\\Users\\swr\\data-store\\verb.json',
     data: { includes: 'swr-readme-includes' } } }

[jonschlinkert]

I might have broken the path resolution in the last updates I did. just to be sure, are you doing anything else that might modify the cwd for the templates?

[jonschlinkert]

also, please create a new issue. I'd like to keep this issue focused on the release

[stefanwalther]

Done, #60

[stefanwalther]

This page still contains a lot of information which one cannot find somewhere else ...!

[tunnckoCore]

Follow READMEs of assemble-core, templates and template - they may help.
Also review all libs of base-* stack by @jonschlinkert :)

All this will give you some image how things will work (and work)