diff --git a/_episodes/03-organization.md b/_episodes/03-organization.md index abf197f3a317e792b160dde6dd39cee49bedf0b8..f4462fed49a716b358d9a996f0a4bf1bc5110ed7 100644 --- a/_episodes/03-organization.md +++ b/_episodes/03-organization.md @@ -9,23 +9,53 @@ objectives: keypoints: - "FIXME" --- -## Common Files +Our lessons need artwork, +CSS style files, +and a few bits of Javascript. +We could load these from the web, +but that would make offline authoring difficult. +Instead, each lesson's repository is self-contained. + +Note: files that appear as top-level items in the navigation menu are stored in the root directory. +Files that appear under the "extras" menu are stored in the `_extras` directory +(which is turned into a [Jekyll collection][jekyll-collection] for easier processing). + +## Standard Files + +The [lesson template]({{ site.template_repo }}) provides the following files +which should *not* be modified: -In order to display properly, our generated HTML pages need artwork, -CSS style files, and a few bits of Javascript. We could load these -from the web, but that would make offline authoring difficult. -Instead, each lesson's repository is self-contained and has a copy of -all these third party resources, and a way of updating them (and only -them) on demand. +* `CONDUCT.md`: the code of conduct. +* `LICENSE.md`: the lesson license. +* `Makefile`: commands for previewing the site, cleaning up junk, etc. +* `_extras/contributing.md`: contribution guidelines. -## Layouts +Run `make` on its own to get a list of targets in the Makefile. -FIXME +## Common Files + +Most lessons will contain the following files which are *not* in the template +(to avoid repeated merge conflicts): -## Inclusions +* `AUTHORS`: names and email addresses of authors. +* `CITATION`: how the lesson should be cited in publications. +* `README.md`: brief description of the lesson displayed by GitHub. +* `index.md`: the home page for the lesson (discussed below). +* `reference.md`: a reference guide for the lesson (discussed below). +* `setup.md`: setup instructions for the lesson (discussed below). +* `_extras/discussion.md`: general discussion. +* `_extras/guide.md`: the instructors' guide. -FIXME +## Layouts and Inclusions + +Page layouts are stored in `_layouts`, +while snippets of HTML included by these layouts are stored in `_includes`, +because that's what [Jekyll][jekyll] requires. ## Assets -FIXME +The `assets` directory contains the CSS, Javascript, fonts, and image files +used in the generated website. + +[jekyll]: http://jekyllrb.com/ +[jekyll-collection]: https://jekyllrb.com/docs/collections/ diff --git a/reference.md b/reference.md new file mode 100644 index 0000000000000000000000000000000000000000..4bfec8ea8cee6880c3903ee60a26452f85aa8f3a --- /dev/null +++ b/reference.md @@ -0,0 +1,6 @@ +--- +layout: reference +title: Reference +permalink: /reference/ +--- +FIXME: reference guide. diff --git a/setup.md b/setup.md new file mode 100644 index 0000000000000000000000000000000000000000..225ae5316b4cae287d394e7b4c1830e291792c16 --- /dev/null +++ b/setup.md @@ -0,0 +1,6 @@ +--- +layout: page +title: Setup +permalink: /setup/ +--- +FIXME: setup instructions.