update/convert docs (templates) to use verb

[jonschlinkert]

Anyone who has edit rights to this can feel free to update the list. thanks!

Before we release Assemble v0.5.0, we'll need to:

• upgrade docs/readme on each repo to use verb or grunt-verb - whichever makes sense based on what the project is already using
• or add verb and a readme template to each project.

This doesn't involve any actual documentation whatsoever, just updating templates/syntax (feel free to edit docs too, but it's not at all expected).

Which repos need this?

We should start with plugins and boilerplates (some of these might be done, I'll update the checkboxes as they are confirmed):

Plugins

• assemble-contrib-anchors
• assemble-contrib-contextual
• assemble-contrib-decompress
• assemble-contrib-download
• assemble-contrib-drafts
• assemble-contrib-i18n
• assemble-contrib-lunr
• assemble-contrib-navigation
• assemble-contrib-pagination
• assemble-contrib-permalinks
• assemble-contrib-rss
• assemble-contrib-sitemap
• assemble-contrib-toc
• assemble-contrib-wordcount

Boilerplates

• boilerplate
• boilerplate-bootstrap
• boilerplate-h5bp
• boilerplate-markdown
• boilerplate-site
• boilerplate-sitemap
• boilerplate-swig
• boilerplates

A couple of suggestions

1. Don't spend too much time on any particular repo - if you can't get verb working, or there is a strange error, just report it here and move on. It's highly likely that I or @doowb know what's causing the error - it's to be expected since we're upgrading templates.
2. Please don't hesitate to ask questions or give feedback on ways to improve.
3. If you want to only partially update a repo, or if you get stuck on something, no worreis. just do a pr with what you have so we can collaborate on what else needs to get done and take it from there. .

Once you get the hang of a few basic concepts with verb each repo should take about 5 minutes . But... you'll likely run into a few errors during the conversion since the syntax for most of the old templates are not compatible with verb. When this happens I'll most likely know exactly what's causing the issue so please don't go crazy trying to figure out what's wrong, just make a comment here with the error if you want help debugging.

Getting started

You'll need to be able to run verb to build the docs as you update them, so before anything else, do:

npm i -g verb-cli generator-verb 

Now, onto upgrading/adding the docs templates!

• upgrading the templates
• adding templates to new repos

Starting from scratch

Here is it in a nutshell:

If a repo doesn't use grunt-readme or verb/grunt-verb, then after git cloning the repo, run:

yo verb:readme

Don't run verb quite yet, but when you're ready to build the docs/readme for the repo, verb-cli will find this file and use it to build the README.md file (might sound crazy, but this file can be both a runtime config file and a markdown template, hence the rc.md).

This is the content of .verbrc.md when it's added by the generator:

# {%= name %} {%= badge("fury") %}

> {%= description %}

## Install
{%= include("install") %}

## Author
{%= contrib("authors") %}

## License
{%= copyright() %}
{%= license() %}
***
{%= include("footer") %}

Next, the content of the old readme into .verbrc.md. beneath the installation section, and just upgrade the header/footer as shown in the images.

Upgrade the docs templates

1. add verb/grunt-verb as a dep

To add grunt-verb or verb devDependency already, do

npm i grunt-verb --save-dev
// or 
npm i verb --save-dev

2. add a .verbrc.md file

If The project doesn't have a docs directory with markdown templates

In the root of the project, if there is not already a file named .verbrc.md, then run yo verb:readme to add one.

Next, if there is a docs directory with a README.tmpl.md template, copy the contents of that file to .verbrc.md then delete the old readme template - but don't delete other files from the docs repo yet.

3. convert templates

Prior to verb we used grunt-readme, so if the project used grunt-readme and hasn't been upgraded to verb yet, then the templates/docs probably have the old template syntax, which looks like this:

{%= _.doc("foo.md") %}

The new looks like this:

// note the lack of underscore and file extension, and "docs" vs doc"
{%= docs("foo") %}

Here is a list of templates that need to be upgraded.

Related repos

You might get an error that says Warning: "repos" is not defined. This means the JSON file for related repos is missing. This is super easy to add.

Install repos with npm: npm i -g repos. Now, to get a list of all assemble repos, you would run repos assemble. But we need to filter this and save them to a specific file.

For plugins run:

repos assemble -d docs/plugins.json -s plugin -n repos

For boilerplates run:

repos assemble -d docs/boilerplates.json -s plugin -n repos

Verb info

• readme template examples and info
• the actual verb readme

[makotot]

When I try to convert docs to use verb in handlebars-helpers repo, I got error like below with grunt verb.

Running "verb:readme" (verb) task
Warning: grunt is not defined Use --force to continue.

Aborted due to warnings.

[doowb]

Have you tried running it without adding the new grunt-verb task? Also, if you forked the repo and pushed your changes up to a branch on your repo, we can pull that down to take a closer look. Thanks for helping out.

[jonschlinkert]

@makotot the handlebars-helpers repo has a few things that make it more difficult to convert than others. I can take a look if you need help still

[makotot]

@doowb @jonschlinkert
Thanks.
I've pushed to my repo https://github.com/makotot/handlebars-helpers/tree/verb.
grunt-verb task is added. It looks like a problem with {%= grunt.template.date("FullDate") %} and {%= grunt.template.today('yyyy') %}. Can I replace these with {%= date('FullDate') %}? Then temporarily remove it, another problem like below occur.

Running "verb:readme" (verb) task
  grunt-verb [nomatch] · verb could not find a match for {%= include("CHANGELOG") %}
Warning: ENOENT, no such file or directory 'undefined' Use --force to continue.

Aborted due to warnings.

When remove {%= include("CHANGELOG") %} also temporarily, error message changes like below.

Running "verb:readme" (verb) task
Warning: Unable to write "/Users/makototateno/dev/handlebars-helpers/README.md/.verbrc.md" file (Error code: ENOTDIR). Use --force to continue.

Aborted due to warnings.

[jonschlinkert]

great, I'll take a look! thanks!

[jonschlinkert]

@makotot I sent a PR to your repo: makotot/handlebars-helpers#1

[makotot]

@jonschlinkert
Thanks! I've merged your PR and just sent PR to assemble/handlebars-helpers repo now.

[jonschlinkert]

👍 merged!

[makotot]

Hmm, if .travis.yml is not exist in a repo like assemble-contrib-anchors, verb task will fail.

Running "verb:readme" (verb) task
Warning: travis is not defined Use --force to continue.

Aborted due to warnings.

Any suggestions?

[jonschlinkert]

in the readme template, try removing the if statement that refers to travis, e.g. {% if (travis) { %}...

we now use {%= badge("travis") %}, but I don't think that repo should have the travis badge. thanks for letting me know!

[makotot]

@jonschlinkert
Okay, thanks!

[Melindrea]

This looks like a good exercise. I'll pick up assemble-contrib-sitemap, unless someone else is on it.

[jonschlinkert]

👍 I'm really excited that you're all helping out! it's a great chance for me to get feedback too! so let me know what doesn't make sense, or how we can improve things so that verb/assemble are easier for newcomers to learn.

fwiw, I should put a video together for verb, it's a more powerful and interesting project than it might seem at first. in the next version, when most of the core modules get split into separate repos I think it will start to make more sense what verb is capable of doing.

[jonschlinkert]

@Melindrea, btw with assemble-contrib-sitemap you will probably need to remove the travis template as well (mentioned here: #501 (comment))

[makotot]

@jonschlinkert
Please update the checkboxes. I think it was almost complete.
BTW boilerplate-gist-blog repo is not found. Is the repo renamed?

[jonschlinkert]

boilerplate-gist-blog

Yes, I retired the repo! sorry, I'll remove it from the list

[jonschlinkert]

done! thank you @makotot and everyone who helped with this!

Next, we're going to start refactoring the actual boilerplates to use assemble v0.5.0 if you're interested!