Skip to content
README.md 2.26 KiB
Newer Older
Greg Wilson's avatar
Greg Wilson committed

Greg Wilson's avatar
Greg Wilson committed
This repository shows how to create a lesson using
the [Software Carpentry lesson template][swc-lesson-template],
Greg Wilson's avatar
Greg Wilson committed
and is itself an example of the use of that template.
Greg Wilson's avatar
Greg Wilson committed

1.  Do *not* fork this repository directly on GitHub.
Greg Wilson's avatar
Greg Wilson committed
    Instead, please follow the instructions in [the setup instructions][setup]
Greg Wilson's avatar
Greg Wilson committed
    to create a repository for your lesson from
Greg Wilson's avatar
Greg Wilson committed
    [the template repository][styles].
Greg Wilson's avatar
Greg Wilson committed

2.  Once you have created the repository,
Greg Wilson's avatar
Greg Wilson committed
    please go through [the episodes][rendered] to format your lesson.
Greg Wilson's avatar
Greg Wilson committed
3.  Please keep the master copy of your lesson in your repository's `gh-pages` branch,
    since that is what is
Greg Wilson's avatar
Greg Wilson committed
    [automatically published as a website by GitHub][github-pages].
Greg Wilson's avatar
Greg Wilson committed
    To simplify reviewing,
    please make changes in feature branches
Greg Wilson's avatar
Greg Wilson committed
    and then submit pull requests against the `gh-pages` branch
    of your lesson's repository.
Greg Wilson's avatar
Greg Wilson committed
The layout of this repository is explained in [this site's episodes][rendered].
In brief:
1.  The source for pages that appear as direct items in the navigation bar
    are stored in the root directory.
2.  Source files for lesson episodes are stored in `_episodes`
    so that we can make use of [Jekyll collections][collections];
    `_episodes/01-xyz.md` generates `/01-xyz/index.html`,
    which can be linked to using `/01-xyz/`.
3.  Files that appear under the "extras" menu pulldown are stored in `_extras`.
4.  Figures and other files are stored in the `files` directory,
    while data sets are stored in `data`
    and source code for examples in `code`.
Greg Wilson's avatar
Greg Wilson committed
1.  Run `bin/lesson-initialize` to create files
    that can't be stored in the template repository
    (because they would cause repeated merge conflicts),
Greg Wilson's avatar
Greg Wilson committed
    then edit `_config.yml` as described in the episode on organization.
Greg Wilson's avatar
Greg Wilson committed
2.  For a list of helpful commands run `make` in this directory.
    If you are looking for things to work on,
    please see [the list of issues for this repository][issues].

[collections]: https://jekyllrb.com/docs/collections/
Greg Wilson's avatar
Greg Wilson committed
[github-pages]:(https://help.github.com/articles/creating-project-pages-manually/
[issues]: https://github.com/swcarpentry/lesson-example/issues/
[rendered]: https://swcarpentry.github.io/lesson-example/
Greg Wilson's avatar
Greg Wilson committed
[setup]: setup.md
[styles]: https://github.com/swcarpentry/styles/