From e22d8e92aeec9478e80161df4aed99e6341497dc Mon Sep 17 00:00:00 2001
From: Greg Wilson <gvwilson@third-bit.com>
Date: Sat, 16 Apr 2016 16:02:03 -0400
Subject: [PATCH] Stock files
---
_episodes/03-organization.md | 54 ++++++++++++++++++++++++++++--------
reference.md | 6 ++++
setup.md | 6 ++++
3 files changed, 54 insertions(+), 12 deletions(-)
create mode 100644 reference.md
create mode 100644 setup.md
diff --git a/_episodes/03-organization.md b/_episodes/03-organization.md
index abf197f..f4462fe 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 0000000..4bfec8e
--- /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 0000000..225ae53
--- /dev/null
+++ b/setup.md
@@ -0,0 +1,6 @@
+---
+layout: page
+title: Setup
+permalink: /setup/
+---
+FIXME: setup instructions.
--
GitLab