Updating documentation

since each lesson will change some of its value,

which would result in merge collisions each time the lesson was updated from the template.

Instead,

the [template]({{ site.template_repo }}) contains a script called `bin/initialize`

which should be run *once* to create an initial `_config.yml` file.

the [template]({{ site.template_repo }}) contains a script called `bin/lesson_initialize.py`

which should be run *once* to create an initial `_config.yml` file

(and a few other files as well).

The author should then edit the values in the top half of the file.

The [template]({{ site.template_repo }}) also contains `_config_dev.yml`,

## Checking

The lesson template includes a Python program to check

The template includes a Python program to check

whether lesson files conform to our template.

You can run this using `make lesson-check`,

which in turn invokes `bin/lesson_check.py` and `bin/markdown_ast.rb`.

and uses Jekyll's own Markdown parser (called Kramdown)

so that we are guaranteed to be checking the same dialect of Markdown that Jekyll uses on GitHub.

The template also includes `bin/repo_check.py`,

which can be invoked by running `make repo-check`.

This program looks in `_config.yml` to find the repository's URL,

then checks that the repository has the right labels set up for issues and pull requests.

Other checks will be added as time goes by.

## Previewing

[Jekyll][jekyll] can be used in two ways:

> Use the `.prereq` style to specify prerequisites.

{: .prereq}

> ## Ten Things You Need To Know

>

> 0.  Don't panic.

> 1.  Create a new lesson by using GitHub Import, *not* by forking.

> 2.  Run `bin/lesson_inititialize.py` *once* in a new lesson repository to set up standard files.

> 3.  Run `make lesson-check` to check that the lesson is formatted correctly.

> 4.  Put lesson episodes in `_episodes` (or `_episodes_rmd` if you are writing in RMarkdown).

> 5.  Run `make serve` to preview the lesson website locally.

> 6.  Do *not* commit the generated HTML files in the `_site` directory.

> 7.  Style blocks and code samples by putting `{: .stylename}` *after* the block or code.

> 8.  Put solutions inside challenges using nested blockquotes.

> 9.  File issues and template fixes in the [styles repository][styles],

>     and enhancements to this documentation in this one.

{: .checklist}

[contributing]: {{ site.repo }}/blob/gh-pages/CONTRIBUTING.md

[styles]: https://github.com/swcarpentry/styles/